How hcmut-brogrammers/codes-backend works
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.