# jphacks/sp_2509 architecture

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

- Interactive diagram: https://gitdiagram.com/jphacks/sp_2509
- Repository: https://github.com/jphacks/sp_2509

## Overview

##### 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”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U["User Device (Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextApp["Next.js App"]:::frontend
        UI["UI Components"]:::frontend
        Canvas["DrawingCanvas.tsx"]:::frontend
        MapComp["MapComponents.tsx"]:::frontend
        Button["RoutingButton.tsx"]:::frontend
        DrawPage["draw/page.tsx"]:::frontend
        APIClient["API Client (route.ts)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        FastAPI["FastAPI Service (main.py)"]:::backend
        Controllers["Controllers/Routers"]:::backend
        Logic["Business Logic"]:::backend
        GpsGen["gps_art_generator.py"]:::backend
        PathMaker["path_maker.py"]:::backend
        TestConsole["test_console.py"]:::backend
        Models["models.py"]:::backend
        Schemas["schemas.py"]:::backend
        DBLayer["Database Layer"]:::backend
        DBConn["database.py"]:::backend
        Seed["seed.py"]:::backend
    end

    %% Database
    DB(("SQLite Database")):::db

    %% External Service
    OSM(("OpenStreetMap (OSMNX)")):::external

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        CI["GitHub Actions"]:::ci
        Vercel["Vercel"]:::ci
    end

    %% Data Flows
    U -->|draw shape| Canvas
    Canvas -->|polyline data| NextApp
    NextApp -->|uses API Client| APIClient
    APIClient -->|"HTTPS POST /generate"| FastAPI
    FastAPI -->|"invoke Business Logic"| GpsGen
    FastAPI -->|"invoke Business Logic"| PathMaker
    GpsGen -->|"rotate→sample→merge"| Logic
    PathMaker -->|compute segments| Logic
    FastAPI -->|"fetch graph"| OSM
    FastAPI -->|"SQL INSERT/SELECT"| DB
    DB -->|"persist route"| DBLayer
    FastAPI -->|"return GeoJSON"| APIClient
    APIClient -->|render route| MapComp

    CI -->|"run lint & build"| NextApp
    CI -->|"run pytest"| FastAPI
    CI -->|"deploy on success"| Vercel

    %% Click Events
    click NextApp "https://github.com/jphacks/sp_2509/tree/main/frontend/"
    click UI "https://github.com/jphacks/sp_2509/tree/main/frontend/src/components/"
    click Canvas "https://github.com/jphacks/sp_2509/blob/main/frontend/src/components/DrawingCanvas.tsx"
    click MapComp "https://github.com/jphacks/sp_2509/blob/main/frontend/src/components/MapComponents.tsx"
    click Button "https://github.com/jphacks/sp_2509/blob/main/frontend/src/components/RoutingButton.tsx"
    click DrawPage "https://github.com/jphacks/sp_2509/blob/main/frontend/src/app/draw/page.tsx"
    click APIClient "https://github.com/jphacks/sp_2509/blob/main/frontend/src/app/api/[...path]/route.ts"
    click FastAPI "https://github.com/jphacks/sp_2509/blob/main/backend/main.py"
    click GpsGen "https://github.com/jphacks/sp_2509/blob/main/backend/calculator/gps_art_generator.py"
    click PathMaker "https://github.com/jphacks/sp_2509/blob/main/backend/calculator/path_maker.py"
    click TestConsole "https://github.com/jphacks/sp_2509/blob/main/backend/calculator/test_console.py"
    click Models "https://github.com/jphacks/sp_2509/blob/main/backend/models.py"
    click Schemas "https://github.com/jphacks/sp_2509/blob/main/backend/schemas.py"
    click DBConn "https://github.com/jphacks/sp_2509/blob/main/backend/database.py"
    click Seed "https://github.com/jphacks/sp_2509/blob/main/backend/seed.py"
    click CI "https://github.com/jphacks/sp_2509/blob/main/.github/workflows/ci.yml"
    click Vercel "https://github.com/jphacks/sp_2509/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#BBE1FA,stroke:#333,stroke-width:1px
    classDef backend fill:#C2F784,stroke:#333,stroke-width:1px
    classDef db fill:#FFCC80,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3F3,stroke:#333,stroke-width:1px
    classDef ci fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef user fill:#F0E68C,stroke:#333,stroke-width:1px
```
