# zijie1119/traffichero-backend architecture

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

- Interactive diagram: https://gitdiagram.com/zijie1119/traffichero-backend
- Repository: https://github.com/zijie1119/traffichero-backend

## Overview

##### Project Type and Purpose
- This is a monolithic backend service (“TrafficHero-Backend”) built with FastAPI.
- It exposes REST endpoints (via uvicorn/main.py) that:
- Fetch and process traffic data (Traffic/pbs.py, Traffic/tdx.py)
- Persist and query data in MongoDB (MongoDB/MongoDB.py)
- Forward or augment requests via OpenAI’s ChatGPT API (OpenAI/ChatGPT.py)

##### File-Structure Analysis
- Top-level entrypoint:
- main.py (registers FastAPI routes, mounts handlers)
- Subdirectories by concern:
- FastAPI/metadata.py  →  API metadata, models, schemas
- Traffic/…           →  Business logic for external traffic data sources
- MongoDB/…           →  Data-access layer to MongoDB
- OpenAI/…            →  Integration layer with OpenAI ChatGPT API
- Document/… holds installation requirements and deployment hints

##### Key README Insights
- “pip install -r requirements.txt” installs dependencies for FastAPI, pymongo, openai, etc.
- Launch command “uvicorn main:app --reload” indicates a single FastAPI app serving on port 8000
- Swagger UI is the built-in API documentation

##### Components
a. Client Layer
- Web/mobile client or API consumer
- Postman / Swagger UI
b. API Layer
- Uvicorn HTTP Server
- FastAPI application (main.py + routers)
c. Service Layer (Three modules)
1. TrafficService
- pbs.py (fetch PBS traffic data)
- tdx.py (fetch TDX traffic data)
2. ChatGPTService
- ChatGPT.py (wraps OpenAI API calls)
3. DatabaseService
- MongoDB.py (CRUD operations via PyMongo)
d. External Dependencies
- PBS API endpoint
- TDX API endpoint
- OpenAI ChatGPT API
e. Data Store
- MongoDB instance

##### Relationships & Data-Flow
- Client → HTTP(S) request → Uvicorn/FastAPI
- FastAPI router → invokes appropriate service module
- TrafficService fetches from PBS/TDX → processes → optionally stores/fetches from MongoDB
- ChatGPTService sends prompt → OpenAI API → receives response → may store in MongoDB
- Service → DatabaseService → MongoDB
- Responses propagate back up to the client

##### Architectural Patterns & Design Principles
- Layered architecture (API layer | Service layer | Data layer)
- Separation of concerns: traffic logic, AI logic, persistence logic
- Single FastAPI app (monolith), not a distributed microservice system
- Dependency injection (FastAPI dependencies) for clients to MongoDB and OpenAI

##### Technologies & Frameworks
- FastAPI (routing, validation, dependency injection)
- Uvicorn (ASGI server)
- PyMongo or motor for MongoDB access
- OpenAI Python SDK for ChatGPT
- Third-party REST APIs (PBS, TDX)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client(("Client")):::client
        Swagger(("Swagger UI / Postman")):::client
    end

    %% API Layer
    subgraph "API Layer"
        Uvicorn["Uvicorn HTTP Server"]:::api
        FastAPIApp["FastAPI App\n(main.py)"]:::api
        Metadata["API Metadata & Schemas\n(metadata.py)"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        subgraph "TrafficService" 
            PBSFetcher["pbs.py"]:::service
            TDXFetcher["tdx.py"]:::service
        end
        ChatGPTService["ChatGPTService\nChatGPT.py"]:::service
        DatabaseService["DatabaseService\nMongoDB.py"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        MongoDB[(MongoDB)]:::data
    end

    %% External Systems
    subgraph "External APIs"
        PBS_API[("PBS API Endpoint")]:::external
        TDX_API[("TDX API Endpoint")]:::external
        OpenAI_API[("OpenAI ChatGPT API")]:::external
    end

    %% Documentation
    subgraph "Documentation"
        Requirements["requirements.txt"]:::docs
        UvicornDoc["uvicornActiveOnOuterNetwork.txt"]:::docs
        README["README.md"]:::docs
    end

    %% Connections
    Client -->|HTTP/HTTPS| Uvicorn
    Swagger -->|HTTP/HTTPS| Uvicorn

    Uvicorn -->|Mount app| FastAPIApp
    FastAPIApp -->|Uses| Metadata

    FastAPIApp -->|Calls| PBSFetcher
    FastAPIApp -->|Calls| TDXFetcher
    FastAPIApp -->|Calls| ChatGPTService

    PBSFetcher -->|Fetch JSON| PBS_API
    TDXFetcher -->|Fetch JSON| TDX_API

    PBSFetcher -->|Read/Write| DatabaseService
    TDXFetcher -->|Read/Write| DatabaseService
    ChatGPTService -->|API Call| OpenAI_API
    ChatGPTService -->|Read/Write| DatabaseService

    DatabaseService -->|CRUD| MongoDB

    %% Click Events
    click FastAPIApp "https://github.com/zijie1119/traffichero-backend/blob/main/main.py"
    click Metadata "https://github.com/zijie1119/traffichero-backend/blob/main/FastAPI/metadata.py"
    click PBSFetcher "https://github.com/zijie1119/traffichero-backend/blob/main/Traffic/pbs.py"
    click TDXFetcher "https://github.com/zijie1119/traffichero-backend/blob/main/Traffic/tdx.py"
    click ChatGPTService "https://github.com/zijie1119/traffichero-backend/blob/main/OpenAI/ChatGPT.py"
    click DatabaseService "https://github.com/zijie1119/traffichero-backend/blob/main/MongoDB/MongoDB.py"
    click Requirements "https://github.com/zijie1119/traffichero-backend/blob/main/Document/requirements.txt"
    click UvicornDoc "https://github.com/zijie1119/traffichero-backend/blob/main/Document/uvicornActiveOnOuterNetwork.txt"
    click README "https://github.com/zijie1119/traffichero-backend/blob/main/README.md"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef api fill:#EBF5FB,stroke:#2E86C1,color:#1B4F72;
    classDef service fill:#EAFAF1,stroke:#28B463,color:#145A32;
    classDef data fill:#FEF9E7,stroke:#F1C40F,color:#7D6608,shape:cylinder;
    classDef external fill:#FDEBD0,stroke:#EB984E,color:#7E5109;
    classDef docs fill:#F5EEF8,stroke:#BB8FCE,color:#4A235A;
```
