How zijie1119/traffichero-backend works
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)