# escalopa/vego architecture

> Architecture diagram of the GitHub repository escalopa/vego, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/escalopa/vego
- Repository: https://github.com/escalopa/vego

## Overview

- Frontend (fe):
- Next.js Application – Represents the user interface and pages (login, call, OAuth callback, etc.).
- UI Components – Display components and hooks (like use-auth, use-webrtc) that handle state and interactions.
- API Client Layer – A module (in fe/lib) where API calls are made to the backend endpoints.
- Backend (be):
- API Server – The Go application starting from be/cmd/main.go centralizes the API endpoints.
- Authentication Service – Includes files under be/internal/auth; handles JWT, OAuth flows and token handling.
- Room Service – Includes managing room logic, WebSocket connections, and WebRTC signaling (see be/internal/room).
- Database Layer – Encapsulated in be/internal/db for database operations.
- Application/Business Logic – Managed within be/internal/app, be/internal/service, and be/internal/domain.
- External Components:
- OAuth Providers – External identity providers like Google or GitHub.
- Client devices – The end-user’s browser interacting with the system.
- (Optionally) Containerization and Deployment – Represent Docker (Dockerfile, docker-compose.yml) which orchestrates the deployment environment.

##### Relationships and Data Flows
- The frontend sends HTTP requests (GET/POST) to the backend API endpoints (e.g., OAuth login, user info retrieval, room join, logout).
- Upon joining a room, the frontend initiates a WebSocket connection to the backend for real-time communication.
- During OAuth login, the backend interacts with external OAuth providers, and then sends authentication tokens back to the client.
- Database access flows, with the backend reading from and writing to the database via the db layer.
- Internal communication among backend services (authentication → configuration & logging, room service → WebSocket hub, etc.) should be clearly shown with connecting lines.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Notice that each major functionality (authentication, room management, business logic, configuration, database) is divided into its own internal package.
- Modularization: Both the frontend and backend are modular (e.g., different directories for API, hooks, components in fe, and different internal modules in be).
- Real-time Communication: Special emphasis on the room module and WebSocket implementation, as detailed in the README for real-time messaging and WebRTC negotiation.
- Container-based Deployment: Indicate that the backend (and possibly the overall application) are containerized using Docker and managed via docker-compose.

##### Relevant Technologies and Frameworks
- For the frontend: Next.js, TypeScript, TailwindCSS, and various UI libraries/components.
- For the backend: Go (Golang), JWT for authentication, OAuth integration, WebSocket handling, and potential database technology (the actual DB system isn’t specified but is implied by the presence of a db package).
- Deployment: Docker and docker-compose.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    EXT1["OAuth Providers"]:::external
    EXT2["Client Devices (Browser)"]:::external

    %% Deployment & Containerization
    subgraph "Deployment"
        D1["Dockerfile (Backend)"]:::deployment
        D2["docker-compose.yml (Project Root)"]:::deployment
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Next.js Application (Login, Call, OAuth Callback)"]:::frontend
        FE2["UI Components (Chat, UI Elements)"]:::frontend
        FE3["API Client Layer"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE1["API Server"]:::backend
        BE2["Authentication Service (OAuth & JWT)"]:::backend
        BE3["Room Service (WebSocket & WebRTC)"]:::backend
        BE4["Database Layer"]:::backend

        subgraph "Business Logic"
            BL1["Application Logic"]:::backend
            BL2["Service Layer (and Mocks)"]:::backend
            BL3["Domain Layer"]:::backend
        end
    end

    %% Data Flows
    EXT2 -->|"HTTPRequest"| FE1
    FE1 -->|"HTTPRequests"| BE1
    FE1 -->|"WebSocketInit"| BE3
    BE1 -->|"AuthRequest"| BE2
    BE2 -->|"OAuthRequest"| EXT1
    EXT1 -->|"OAuthResponse"| BE2
    BE1 -->|"DBQuery"| BE4
    BE1 -->|"BusinessCall"| BL1
    BE1 -->|"BusinessCall"| BL2
    BE1 -->|"BusinessCall"| BL3
    D2 -->|"Deploys"| FE1
    D2 -->|"Deploys"| BE1
    D1 -->|"Containerizes"| BE1

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C7F0DB,stroke:#333,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef deployment fill:#D7DBDD,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE1 "https://github.com/escalopa/vego/tree/main/fe/app"
    click FE2 "https://github.com/escalopa/vego/tree/main/fe/components"
    click FE3 "https://github.com/escalopa/vego/blob/main/fe/lib/api.ts"
    click BE1 "https://github.com/escalopa/vego/blob/main/be/cmd/main.go"
    click BE2 "https://github.com/escalopa/vego/tree/main/be/internal/auth"
    click BE2 "https://github.com/escalopa/vego/blob/main/be/internal/app/auth.go"
    click BE3 "https://github.com/escalopa/vego/tree/main/be/internal/room"
    click BE4 "https://github.com/escalopa/vego/tree/main/be/internal/db"
    click BL1 "https://github.com/escalopa/vego/tree/main/be/internal/app"
    click BL2 "https://github.com/escalopa/vego/tree/main/be/internal/service"
    click BL2 "https://github.com/escalopa/vego/tree/main/be/internal/service/mock"
    click BL3 "https://github.com/escalopa/vego/tree/main/be/internal/domain"
    click D1 "https://github.com/escalopa/vego/tree/main/be/Dockerfile"
    click D2 "https://github.com/escalopa/vego/blob/main/docker-compose.yml"
```
