# flash019/stackit_backend architecture

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

- Interactive diagram: https://gitdiagram.com/flash019/stackit_backend
- Repository: https://github.com/flash019/stackit_backend

## Overview

##### Project type and purpose
- This is a backend microservice (“StackIt-Backend”) built with FastAPI and MongoDB.
- Purpose: a Q&A system with JWT‐based authentication, real-time WebSocket notifications, background tasks, and standard CRUD operations for questions/answers.

##### File structure
- **main.py**: entry point that instantiates FastAPI, mounts middleware and routers.
- **routers/**: controller layer (HTTP endpoints grouped by feature: auth, questions, answers, notifications, WebSocket, search, admin, votes).
- **services/**: business‐logic layer (services invoked by routers).
- **repository/**: data‐access layer (MongoDB queries, user repository).
- **models/**: Pydantic models and domain schemas.
- **utils/**: auxiliary modules (JWT helpers, token generation, auth utilities).
- **middleware/**: cross‐cutting concerns (rate limiting).
- **database.py** & **hashing.py**: DB connection and password‐hashing utilities.
- **requirements.txt** and the venv structure establish dependencies (FastAPI, Uvicorn, pymongo, python-jose, etc.).

##### README for additional insights
- Highlights FastAPI (async API), MongoDB storage, Swagger UI docs (`/docs` & `/redoc`), background tasks, WebSocket support, and typical deployment via Render.

##### Main components
a. Clients
- Admin Panel (browser)
- User Panel (browser/mobile app)
b. API Layer
- ASGI Server (Uvicorn/Gunicorn)
- FastAPI App
c. Layered Architecture
- Router (Controllers)
- Service (Business Logic)
- Repository (Data Access)
- Models (Schemas/Pydantic)
d. Cross­-cutting
- Middleware (Rate Limiter)
- Utils (JWT, hashing)
- Background Task Manager (FastAPI’s `BackgroundTasks`)
e. Database
- MongoDB cluster/instance
f. Real­-time
- WebSocket Endpoint (notifications_ws)
g. External/Infrastructure
- Swagger UI / ReDoc docs
- Host/Deployment Platform (e.g., Render)

##### Relationships and interactions
- Client → HTTP/WebSocket requests → API Layer
- API Layer → Routers → Services → Repositories → MongoDB
- Middleware intercepts at the API Layer (rate‐limit)
- Authentication: JWT utils invoked by routers/services
- Background tasks invoked by routers/services enqueue notification jobs
- WebSocket endpoint pushes real‐time events to connected clients

##### Architectural patterns & design principles
- Layered (Controller → Service → Repository) — clear separation of concerns
- Hexagonal/Ports & Adapters: business logic decoupled from transport (HTTP vs. WebSocket)
- Async throughout: FastAPI + asyncio + background tasks
- Security by design: JWT + role-based access

##### Relevant technologies/frameworks
- FastAPI (routers, dependency injection, background tasks, WebSockets)
- Uvicorn (ASGI server)
- Pydantic (request/response models)
- PyMongo (MongoDB driver)
- python-jose (JWT)
- Middleware for rate limiting
- Hosting on Render (CI/CD integration)

##### Detail & labeling
- Non-blocking operations (async + background tasks)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        Admin["Admin Panel (Browser)"]:::client
        User["User Panel (Browser/Mobile)"]:::client
    end

    %% API Server
    subgraph "API Server"
        direction TB
        ASGI["ASGI Server<br>(Uvicorn)"]:::infra
        FastAPI["FastAPI App"]:::app

        subgraph "Middleware & Utils"
            direction TB
            RateLimit["Rate Limiting Middleware"]:::utils
            AuthUtil["Auth Utilities"]:::utils
            JWTUtil["JWT Token Helpers"]:::utils
            TokenUtil["Generic Token Utilities"]:::utils
        end

        subgraph "Routers (Controllers)"
            direction TB
            AuthCtrl["Authentication Controller"]:::controller
            QsCtrl["Questions Controller"]:::controller
            QCtrl["Single Question Controller"]:::controller
            AnsCtrl["Answers Controller"]:::controller
            VotesCtrl["Votes Controller"]:::controller
            SearchCtrl["Search Controller"]:::controller
            NotifCtrl["Notifications HTTP Controller"]:::controller
            WSNotif["Notifications WebSocket Endpoint"]:::controller
            AdminCtrl["Admin Panel Controller"]:::controller
            UserCtrl["User Management Controller"]:::controller
            FlagCtrl["Flagging Controller"]:::controller
        end

        subgraph "Services (Business Logic)"
            direction TB
            AdminSvc["Admin Service"]:::service
        end

        subgraph "Repository (Data Access)"
            direction TB
            UserRepo["User Repository"]:::repo
        end

        subgraph "Background Tasks"
            direction TB
            BGTask["Background Task Manager"]:::infra
        end

    end

    %% Database
    MongoDB["MongoDB Cluster"]:::database

    %% External/Infra
    subgraph "External / Infra"
        Docs["Swagger UI / ReDoc"]:::infra
        Deploy["Render Deployment"]:::infra
    end

    %% Connections
    Admin -->|HTTP/WS| ASGI
    User -->|HTTP/WS| ASGI
    ASGI -->|mount| FastAPI

    FastAPI -->|uses| RateLimit
    FastAPI -->|injects| AuthUtil
    FastAPI -->|injects| JWTUtil
    FastAPI -->|injects| TokenUtil

    FastAPI -->|routes to| AuthCtrl
    FastAPI -->|routes to| QsCtrl
    FastAPI -->|routes to| QCtrl
    FastAPI -->|routes to| AnsCtrl
    FastAPI -->|routes to| VotesCtrl
    FastAPI -->|routes to| SearchCtrl
    FastAPI -->|routes to| NotifCtrl
    FastAPI -->|routes to| WSNotif
    FastAPI -->|routes to| AdminCtrl
    FastAPI -->|routes to| UserCtrl
    FastAPI -->|routes to| FlagCtrl

    AuthCtrl -->|calls| AdminSvc
    QsCtrl -->|calls| AdminSvc
    QCtrl -->|calls| AdminSvc
    AnsCtrl -->|calls| AdminSvc
    VotesCtrl -->|calls| AdminSvc
    SearchCtrl -->|calls| AdminSvc
    NotifCtrl -->|calls| AdminSvc
    WSNotif -->|calls| AdminSvc
    AdminCtrl -->|calls| AdminSvc
    UserCtrl -->|calls| AdminSvc
    FlagCtrl -->|calls| AdminSvc

    AdminSvc -->|uses| UserRepo
    AdminSvc -->|enqueues| BGTask
    BGTask -->|writes| MongoDB
    UserRepo -->|reads/writes| MongoDB

    WSNotif -->|pushes| Admin
    WSNotif -->|pushes| User

    FastAPI -->|serves| Docs
    Deploy -->|hosts| ASGI

    %% Click Events
    click FastAPI "https://github.com/flash019/stackit_backend/blob/main/main.py"
    click ASGI "https://github.com/flash019/stackit_backend/blob/main/app/Scripts/uvicorn.exe"
    click AuthCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/authentication.py"
    click QsCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/questions.py"
    click QCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/question.py"
    click AnsCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/answers.py"
    click VotesCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/votes.py"
    click SearchCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/search.py"
    click NotifCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/notifications.py"
    click WSNotif "https://github.com/flash019/stackit_backend/blob/main/routers/notifications_ws.py"
    click AdminCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/admin.py"
    click UserCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/user.py"
    click FlagCtrl "https://github.com/flash019/stackit_backend/blob/main/routers/flag.py"
    click AdminSvc "https://github.com/flash019/stackit_backend/blob/main/services/admin_service.py"
    click UserRepo "https://github.com/flash019/stackit_backend/blob/main/repository/user.py"
    click RateLimit "https://github.com/flash019/stackit_backend/blob/main/middleware/rate_limit.py"
    click AuthUtil "https://github.com/flash019/stackit_backend/blob/main/utils/auth.py"
    click JWTUtil "https://github.com/flash019/stackit_backend/blob/main/utils/jwt_token.py"
    click JWTUtil "https://github.com/flash019/stackit_backend/blob/main/utils/token_jwt.py"
    click TokenUtil "https://github.com/flash019/stackit_backend/blob/main/utils/token.py"
    click MongoDB "https://github.com/flash019/stackit_backend/blob/main/database.py"
    click MongoDB "https://github.com/flash019/stackit_backend/blob/main/hashing.py"

    %% Styles
    classDef controller fill:#ffa500,stroke:#333,stroke-width:1px
    classDef service fill:#00aaff,stroke:#333,stroke-width:1px
    classDef repo fill:#2ecc71,stroke:#333,stroke-width:1px
    classDef utils fill:#9b59b6,stroke:#333,stroke-width:1px
    classDef database fill:#f1c40f,stroke:#333,stroke-width:1px
    classDef infra fill:#e74c3c,stroke:#333,stroke-width:1px
    classDef client fill:#bdc3c7,stroke:#333,stroke-width:1px
    classDef app fill:#ecf0f1,stroke:#333,stroke-width:1px
```
