# hcmut-brogrammers/codes-backend architecture

> Architecture diagram of the GitHub repository hcmut-brogrammers/codes-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hcmut-brogrammers/codes-backend
- Repository: https://github.com/hcmut-brogrammers/codes-backend

## Overview

Step 1. Identify Project Type and Purpose
- This is a backend‐only service built on FastAPI (Python).
- Purpose: Provide a multi‐tenant design collaboration API (managing users, organizations, invitations, design projects and their elements) with JWT authentication and real‐time updates via WebSockets.
- Key indicators:
- README refers to “FastAPI” and running `fastapi dev main.py`.
- Directory structure under `src/routers`, `src/components`, `src/services`, etc.
- Presence of MongoDB constants and a `database/mongodb.py` adapter.
- Websocket logic under `src/common/websocket` and `src/routers/websocket`.

Step 2. Analyze the File Structure
- Top‐level:
- `src/main.py` – application entrypoint.
- `src/config.py`, `src/dependencies.py`, `Dockerfile`, GitHub workflow.
- API routing layer:
- `src/routers/…` (authenticate, users, organizations, design_projects, join_organization_invitations, websocket)
- Business logic layer (the “components”):
- `src/components/…` – one module per API domain (e.g., `authenticate`, `users`, `design_projects`, etc.)
- Shared/domain models:
- `src/common/models` defines Pydantic schemas for users, tokens, design elements, invitations, organizations.
- Persistence layer:
- `src/database/mongodb.py` – low‐level MongoDB client wrapper
- `src/database/wrapped_db.py` – higher‐level DB interface
- Services/utilities:
- `src/services/jwt_service.py` – JWT encode/decode logic
- `src/common/websocket/connection_manager.py` – real‐time connection management
- `src/utils` – logging, common helpers
- Middleware:
- `src/middlewares/authenticate_middleware.py` – attach user context from JWT
- Configuration/constants:
- `src/constants` – DB names, route prefixes, WebSocket settings

Step 3. Extract Additional Insights from README
- Confirms use of pytest, Docker, Yarn (for Node dependencies, possibly OpenAPI UI assets).

a. Main Components
1. Clients (e.g. frontends / mobile apps / other services)
2. FastAPI Application (single service)
– Routing Layer
– Business Logic Components
– Middleware (Authentication)
– Services Layer (JWT, Websocket manager)
– Persistence Layer (MongoDB adapter)
3. External Systems
– MongoDB Database
– (Optionally) Message Broker if added later
b. Relationships & Interactions
1. Client → HTTP(S) → FastAPI Router → Middleware → Component → Service → Database
2. FastAPI WebSocket Endpoint → Websocket Connection Manager → Broadcast / Push updates
3. JWT Service is invoked by authentication component and middleware to issue/validate tokens
c. Architectural Patterns & Principles
- Layered Architecture: HTTP API → Controllers (routers) → Components (use‐case handlers) → DB layer
- Separation of Concerns: Authentication, Business Logic, Persistence each isolated
- Dependency Injection via FastAPI’s `Depends()` in `dependencies.py`
- Domain‐Driven: domain models (`common/models`) separated from transport models
d. Key Technologies & Frameworks
- FastAPI (web framework)
- Pydantic (data validation & settings)
- PyMongo / Motor (MongoDB client)
- JWT (authentication tokens)
- WebSockets (real‐time features)
- pytest (testing)
- Docker / GitHub Actions (deployment CI/CD)

- Separation between:
- Authentication domain (sign up, token refresh/revoke)
- User & Organization management
- Design project management (with nested “elements” sub‐module)
- WebSocket real‐time channel
- How routers map 1:1 to components.
- Middleware invocation before business logic.

- Use clear rectangles for each logical component:
- e.g. “Authenticate Router”, “Authenticate Component”, “JWT Service”
1. Client → API Gateway (FastAPI)
2. API Gateway → Middleware → Router → Component → DB Adapter → MongoDB
3. Component → Service (JWT or Websocket)
- Blue for API/Routers
- Green for Business Logic/Components
- Orange for Services (JWT, Websocket)
- Gray for Utilities/Shared modules

Step 7. Emphasize Detail & Completeness
- Six domains (authenticate, users, organizations, invitations, design_projects (+ elements), websocket).
- Common modules (`common/models`, `utils`, `middlewares`) feeding into each domain.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client"]:::external

    %% FastAPI Entrypoint & Config
    subgraph "FastAPI Application"
        direction TB
        Main["Main (src/main.py)"]:::app
        Config["Config (src/config.py)"]:::app
        Deps["Dependencies (src/dependencies.py)"]:::app
        Main --> Config
        Main --> Deps

        %% Middleware
        AuthMW["Authenticate Middleware (src/middlewares/authenticate_middleware.py)"]:::middleware

        %% Routing Layer
        subgraph "Routing Layer"
            direction TB
            AuthRouter["Authenticate Router"]:::routers
            UsersRouter["Users Router"]:::routers
            OrgRouter["Organizations Router"]:::routers
            InviteRouter["Invitations Router"]:::routers
            DesignRouter["Design Projects Router"]:::routers
            ElementRouter["Project Elements Router"]:::routers
            WSRouter["WebSocket Router"]:::routers
        end

        %% Business Logic Components
        subgraph "Components Layer"
            direction TB
            AuthComp["Authenticate Component"]:::components
            UsersComp["Users Component"]:::components
            OrgComp["Organizations Component"]:::components
            InviteComp["Invitations Component"]:::components
            SwitchComp["Switch Organization Component"]:::components
            DesignComp["Design Projects Component"]:::components
            ElemComp["Design Elements Sub-component"]:::components
            WSComp["WebSocket Component"]:::components
        end

        %% Services & Utilities
        subgraph "Services & Common"
            direction TB
            JWTService["JWT Service (src/services/jwt_service.py)"]:::services
            ConnMgr["Connection Manager (src/common/websocket/connection_manager.py)"]:::services
            MsgModel["WebSocket Message Model (src/common/websocket/message.py)"]:::common
            Models["Domain Models (src/common/models/)"]:::common
            UtilsCommon["Common Helpers (src/utils/common.py)"]:::common
            UtilsElem["Design Element Helpers (src/utils/design_element.py)"]:::common
            Logger["Logger (src/utils/logger.py)"]:::common
            TokenCtx["Auth Context Models (src/common/auth/)"]:::common
        end

        %% Persistence Layer
        subgraph "Persistence Layer"
            direction TB
            MongoClient["MongoDB Client (src/database/mongodb.py)"]:::database
            WrappedDB["Wrapped DB Interface (src/database/wrapped_db.py)"]:::database
            MongoClient --> WrappedDB
        end

        %% Constants & Interfaces
        Constants["Constants (src/constants/)"]:::common
        Interfaces["Base Component Interface (src/interfaces/base_component.py)"]:::common
    end

    %% Database
    DB["MongoDB"]:::db

    %% Flow: Client to API
    Client -->|"HTTP Request"| AuthMW
    Client -->|"WebSocket Connect"| WSRouter

    %% Middleware to Routers
    AuthMW --> AuthRouter
    AuthMW --> UsersRouter
    AuthMW --> OrgRouter
    AuthMW --> InviteRouter
    AuthMW --> DesignRouter
    AuthMW --> ElementRouter

    %% Routers to Components
    AuthRouter --> AuthComp
    UsersRouter --> UsersComp
    OrgRouter --> OrgComp
    InviteRouter --> InviteComp
    DesignRouter --> DesignComp
    ElementRouter --> ElemComp
    WSRouter --> WSComp

    %% Components to Persistence
    AuthComp --> WrappedDB
    UsersComp --> WrappedDB
    OrgComp --> WrappedDB
    InviteComp --> WrappedDB
    SwitchComp --> WrappedDB
    DesignComp --> WrappedDB
    ElemComp --> WrappedDB
    WSComp --> WrappedDB

    %% Components to Services/Common
    AuthComp --> JWTService
    AuthComp --> Models
    AuthComp --> TokenCtx
    UsersComp --> Models
    OrgComp --> Models
    InviteComp --> Models
    DesignComp --> Models
    ElemComp --> Models
    WSComp --> ConnMgr
    WSComp --> MsgModel
    WSComp --> TokenCtx

    %% Services to Persistence
    JWTService --> WrappedDB
    ConnMgr --> WrappedDB

    %% Persistence to Database
    WrappedDB --> DB

    %% Constants & Interfaces usage
    Main --> Constants
    AuthMW --> Constants
    AuthComp --> Interfaces
    UsersComp --> Interfaces
    OrgComp --> Interfaces
    InviteComp --> Interfaces
    DesignComp --> Interfaces
    ElemComp --> Interfaces

    %% Click Events
    click Main "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/main.py"
    click Config "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/config.py"
    click Deps "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/dependencies.py"
    click AuthRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/authenticate/router.py"
    click UsersRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/users/router.py"
    click OrgRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/organizations/router.py"
    click InviteRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/join_organization_invitations/router.py"
    click DesignRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/design_projects/router.py"
    click ElementRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/design_projects/elements/router.py"
    click WSRouter "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/routers/websocket/router.py"
    click AuthComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/authenticate/"
    click UsersComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/users/"
    click OrgComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/organizations/"
    click InviteComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/join_organization_invitations/"
    click SwitchComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/switch_organization/"
    click DesignComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/design_projects/"
    click ElemComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/design_projects/elements/"
    click WSComp "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/components/websocket/"
    click Models "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/common/models/"
    click ConnMgr "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/common/websocket/connection_manager.py"
    click MsgModel "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/common/websocket/message.py"
    click TokenCtx "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/common/auth/"
    click MongoClient "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/database/mongodb.py"
    click WrappedDB "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/database/wrapped_db.py"
    click JWTService "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/services/jwt_service.py"
    click AuthMW "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/middlewares/authenticate_middleware.py"
    click Constants "https://github.com/hcmut-brogrammers/codes-backend/tree/main/src/constants/"
    click UtilsCommon "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/utils/common.py"
    click UtilsElem "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/utils/design_element.py"
    click Logger "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/utils/logger.py"
    click Interfaces "https://github.com/hcmut-brogrammers/codes-backend/blob/main/src/interfaces/base_component.py"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef app fill:#bbf,stroke:#333;
    classDef middleware fill:#ffa,stroke:#333;
    classDef routers fill:#acf,stroke:#333;
    classDef components fill:#cfc,stroke:#333;
    classDef services fill:#fc9,stroke:#333;
    classDef common fill:#ddd,stroke:#333;
    classDef database fill:#c9f,stroke:#333;
    classDef db fill:#b19cd9,stroke:#333,stroke-width:2px;
    class Main,Config,Deps app
    class AuthMW middleware
    class AuthRouter,UsersRouter,OrgRouter,InviteRouter,DesignRouter,ElementRouter,WSRouter routers
    class AuthComp,UsersComp,OrgComp,InviteComp,SwitchComp,DesignComp,ElemComp,WSComp components
    class JWTService,ConnMgr services
    class Models,MsgModel,TokenCtx,UtilsCommon,UtilsElem,Logger,Constants,Interfaces common
    class MongoClient,WrappedDB database
    class DB db
```
