# wsa-2002/pd6-be architecture

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

- Interactive diagram: https://gitdiagram.com/wsa-2002/pd6-be
- Repository: https://github.com/wsa-2002/pd6-be

## Overview

##### Project type and purpose
- This is a standalone **async web‑backend service** (no built‑in frontend) for “PDOGS 6,” exposing HTTP endpoints via **FastAPI** and handling background tasks via **AMQP** and other async mechanisms.
- Its primary use cases are BREAD operations (Browse, Read, Edit, Add, Delete) on academic resources (accounts, courses, problems, submissions, etc.), plus asynchronous judge pipelines, email notifications, and file/object storage.

##### File structure
- Top‐level components:
- `main.py` – Application entry point (FastAPI + Uvicorn)
- `middleware/` – HTTP middleware layers (authentication, routing, logging, envelope formatting)
- `processor/`
– `http_api/` – Controllers/handlers for each resource
– `amqp/` – AMQP‐driven background consumers
- `service/` – Business logic layer (judging, notifications, scoreboard, RBAC, CSV export)
- `persistence/` – Data access layer
· `database/` – ORM or DAO classes for each table/view
· `amqp_publisher` / `amqp_consumer` – enqueue/dequeue tasks
· `s3/` – object storage interactions
· `email/` – SMTP or email API wrappers
· `http_client/` – calls to external HTTP services
- `base/`, `common/`, `util/` – shared utilities, value objects (VOs), models, enums, metaclasses, context managers
- Config & infra: `.env.example`, `Dockerfile`, `gitlab‑ci.yml`

##### README for technical stack
- Python 3.10 + asyncio
- FastAPI + Uvicorn
- Uses AMQP broker (e.g., RabbitMQ) for background tasks
- Relational database (implied by DAOs in `persistence/database`)
- S3‑compatible storage for large artifacts
- SMTP or third‑party email provider
- Logging via YAML config
- Unit tests orchestrated by `run_test.py`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Context
    subgraph "Clients" 
        direction TB
        WebClient["Web Browser / CLI / Other Services"]:::external
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Server["Uvicorn + FastAPI"]:::frontend
    end

    %% Middleware
    subgraph "Middleware Layer"
        direction TB
        Middleware["Auth / Routing / Logging / Envelope / Profiler / Response / Router / Tracker / DB Access Log"]:::frontend
    end

    %% Controllers
    subgraph "HTTP Controllers"
        direction TB
        Controllers["processor/http_api (account.py, course.py, submission.py, docs.py, public.py, system.py)"]:::frontend
    end

    %% Service
    subgraph "Business Service Layer"
        direction TB
        Services["service (judge.py, submission.py, scoreboard.py, rbac.py, statistics.py, csv.py, task.py, downloader.py, moss.py)"]:::service
    end

    %% Persistence Adapters
    subgraph "Persistence Adapters"
        direction TB
        DBAdapter["Relational DB Adapter\n(persistence/database)"]:::adapter
        AMQPPub["AMQP Publisher Adapter\n(persistence/amqp_publisher)"]:::adapter
        AMQPCon["AMQP Consumer Adapter\n(persistence/amqp_consumer)"]:::adapter
        S3Adapter["S3 Storage Adapter\n(persistence/s3)"]:::adapter
        EmailAdapter["Email Adapter\n(persistence/email)"]:::adapter
        HTTPClient["External HTTP Client Adapter\n(persistence/http_client)"]:::adapter
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        Base["base (cls.py, do.py, enum.py, mcs.py, popo.py, vo.py)"]:::library
        Common["common (config.py, const.py, exceptions/, log.py, logging.yaml.example)"]:::library
        Util["util (api_doc.py, background_task.py, context.py, dtype.py, file.py, metric.py, model.py, security.py, serialize.py, text.py, mock/)"]:::library
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Database["Relational Database"]:::external
        AMQPBroker["AMQP Broker (RabbitMQ)"]:::external
        S3Storage["S3-Compatible Object Storage"]:::external
        SMTP["SMTP / Email Service"]:::external
        ExternalHTTP["Third-Party HTTP APIs"]:::external
    end

    %% CI/CD & Config
    Infra["CI/CD & Infra\n(.env.example, Dockerfile, .gitlab-ci.yml, prestart.sh, requirements*.txt, gitlab/merge_request_templates/)"]:::library

    %% Flows
    WebClient -->|"HTTP request"| Server
    Server -->|"Middleware pipeline"| Middleware
    Middleware -->|"Router dispatch"| Controllers
    Controllers -->|"Invoke"| Services
    Services -->|"SQL/ORM"| DBAdapter
    Services -->|"enqueue AMQP"| AMQPPub
    Services -->|"invoke sync AMQP"| AMQPCon
    Services -->|"S3 API"| S3Adapter
    Services -->|"SMTP/API"| EmailAdapter
    Services -->|"HTTP"| HTTPClient
    Controllers -->|"HTTP response"| WebClient

    %% Adapter to external
    DBAdapter -->|"SQL"| Database
    AMQPPub -->|"AMQP"| AMQPBroker
    AMQPCon -->|"AMQP"| AMQPBroker
    S3Adapter -->|"S3 API"| S3Storage
    EmailAdapter -->|"SMTP"| SMTP
    HTTPClient -->|"HTTP"| ExternalHTTP

    Infra --- Server

    %% Click Events
    click Server "https://github.com/wsa-2002/pd6-be/blob/master/main.py"
    click Server "https://github.com/wsa-2002/pd6-be/blob/master/uvicorn_workers.py"
    click Middleware "https://github.com/wsa-2002/pd6-be/tree/master/middleware/"
    click Controllers "https://github.com/wsa-2002/pd6-be/tree/master/processor/http_api/"
    click AMQPCon "https://github.com/wsa-2002/pd6-be/tree/master/processor/amqp/"
    click AMQPPub "https://github.com/wsa-2002/pd6-be/tree/master/persistence/amqp_publisher/"
    click AMQPCon "https://github.com/wsa-2002/pd6-be/tree/master/persistence/amqp_consumer/"
    click Services "https://github.com/wsa-2002/pd6-be/tree/master/service/"
    click DBAdapter "https://github.com/wsa-2002/pd6-be/tree/master/persistence/database/"
    click S3Adapter "https://github.com/wsa-2002/pd6-be/tree/master/persistence/s3/"
    click EmailAdapter "https://github.com/wsa-2002/pd6-be/tree/master/persistence/email/"
    click HTTPClient "https://github.com/wsa-2002/pd6-be/tree/master/persistence/http_client/"
    click Base "https://github.com/wsa-2002/pd6-be/tree/master/base/"
    click Common "https://github.com/wsa-2002/pd6-be/tree/master/common/"
    click Util "https://github.com/wsa-2002/pd6-be/tree/master/util/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#2B6CB0,color:#1A365D;
    classDef service fill:#DFFFE0,stroke:#38A169,color:#22543D;
    classDef adapter fill:#FFF5E6,stroke:#DD6B20,color:#7B341E;
    classDef library fill:#F0F0F0,stroke:#A0AEC0,color:#4A5568;
    classDef external fill:#FFE5E5,stroke:#E53E3E,color:#742A2A;
```
