How jphacks/sp_2509 works
Project Type and Purpose
• The frontend is built with Next.js + TypeScript + Leaflet.js for map rendering.
• The backend is a FastAPI service in Python, using OSMNX to fetch OpenStreetMap data, a custom Dijkstra-based algorithm to compute partial routes, and SQLite for persistence.
• CI/CD is implemented via GitHub Actions; the frontend is deployed on Vercel.
Main Components
a. User Device (Browser/Mobile)
b. Frontend Web App (Next.js)
– UI Components (drawing canvas, map, buttons)
– API Client (fetch/post to backend)
– Map Renderer (Leaflet.js)
c. API Gateway / Backend (FastAPI)
– Controllers / Routers (endpoints in main.py)
– Business Logic (“calculator” package: gps_art_generator.py, path_maker.py)
– Data Models & Schemas (models.py, schemas.py)
– Persistence Layer (SQLite via database.py + seed.py)
d. External Service
– OpenStreetMap data via OSMNX library
e. CI/CD Pipeline
– GitHub Actions (ci.yml, deploy.yml)
– Vercel (frontend hosting and serverless backend)
Relationships & Data Flows
3. Backend Controller invokes Business Logic:
• Fetch map graph from OSMNX
• Run modified Dijkstra for each segment → merge segments
4. Backend stores generated route in SQLite (via ORM models)
5. Backend returns route data (GeoJSON) to frontend
6. Frontend renders route on Leaflet map; user can save/favorite/delete via additional API calls
7. GitHub Actions run on each PR/push:
• Frontend: lint + build
• Backend: pytest unit tests
• On success, deploy frontend to Vercel and backend as serverless functions
Architectural Patterns & Principles
• Layered architecture in the backend:
• API Layer (FastAPI routers)
• Service Layer (calculator logic)
• Data Layer (database module)
• RESTful API design with clear schemas (Pydantic)
• Single-page application on the frontend, consuming backend JSON APIs
• CI/CD ensures quality and automates deployment
Essential Elements
• Clear component labels (e.g., “Next.js App”, “FastAPI /generate endpoint”, “RouteCalculator”)
• Notes or annotations for key algorithms (e.g., “Custom Dijkstra: rotate → sample → merge”)