# gdg-cnu/netradar architecture

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

- Interactive diagram: https://gitdiagram.com/gdg-cnu/netradar
- Repository: https://github.com/gdg-cnu/netradar

## Overview

NetRadar is a taxi-driver service for viewing hourly-earnings forecasts, finding detour routes, recording a drive, and reviewing trip history; it also supports account, profile, and favorite-place management. The main flow runs from login and map exploration through route selection, drive events, and replay. The README documents the frontend-to-FastAPI contracts and demo/live modes. Source-index references and excerpts support the depicted module links; unsampled details are represented at subsystem level, and unverified external integrations are omitted or marked optional.

Main entry points: [`front/src/App.tsx`](https://github.com/gdg-cnu/netradar/blob/main/front/src/App.tsx) (App shell), [`backend/main.py`](https://github.com/gdg-cnu/netradar/blob/main/backend/main.py) (FastAPI app), [`backend/routers/routes.py`](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/routes.py) (Recommendations), [`front/src/services/api.ts`](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Driver app"]
  node_app["App shell<br/>[App.tsx]"]
  node_login["Login<br/>[LoginPage.tsx]"]
  node_forecast["Earnings map<br/>[MapPage.tsx]"]
  node_forecast_ui["Forecast views"]
  node_route_page["Route planning<br/>[RoutePage.tsx]"]
  node_place_search["Place search<br/>[PlaceSearch.tsx]"]
  node_route_results["Route results<br/>[RouteResults.tsx]"]
  node_drive_page["Drive guidance<br/>[DrivePage.tsx]"]
  node_drive_state["Drive state<br/>[useDrive.ts]"]
  node_replay["Trip replay<br/>[ReplayPage.tsx]"]
  node_profile["Profile<br/>[MyPage.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_route_service["Route service<br/>[routes.ts]"]
  node_forecast_service["Forecast service<br/>[forecast.ts]"]
  node_profile_service["Profile service<br/>[profile.ts]"]
  node_history_service["History service<br/>[history.ts]"]
end

subgraph group_backend["FastAPI services"]
  node_api_server["FastAPI app<br/>[main.py]"]
  node_forecast_api["Forecast endpoint<br/>[forecast.py]"]
  node_places_api["Places endpoint<br/>[places.py]"]
  node_routes_api["Recommendations<br/>[routes.py]"]
  node_profile_api["Profile endpoint<br/>[profile.py]"]
  node_trips_api["Trip events<br/>[trips.py]"]
  node_route_schema["Route contracts<br/>[route.py]"]
end

subgraph group_data["Backend data"]
  node_zones["Sample zones<br/>[mock_zones.py]"]
  node_places["Sample places<br/>[mock_places.py]"]
end

subgraph group_identity["Identity and storage"]
  node_storage[("Browser storage<br/>[storage.ts]")]
  node_session["Session state<br/>[useAppSession.ts]"]
  node_supabase_client["Supabase client<br/>[client.py]"]
  node_auth_guard["Token validation<br/>[auth.py]"]
end

subgraph group_external["External providers"]
  node_supabase_auth["Supabase auth<br/>[auth.ts]"]
  node_kakao["Kakao Mobility<br/>[kakao_mobility.py]"]
end

node_driver(("Taxi driver"))

node_driver -->|"opens"| node_app
node_app -->|"checks session"| node_session
node_app -->|"shows when signed out"| node_login
node_app -->|"routes to"| node_forecast
node_app -->|"routes to"| node_route_page
node_app -->|"routes to"| node_drive_page
node_app -->|"routes to"| node_replay
node_app -->|"routes to"| node_profile
node_session -->|"reads session"| node_supabase_auth
node_session -->|"sets account scope"| node_storage
node_login -->|"authenticates"| node_supabase_auth
node_forecast -->|"renders"| node_forecast_ui
node_forecast -->|"loads forecasts"| node_forecast_service
node_route_page -->|"uses"| node_place_search
node_route_page -->|"renders"| node_route_results
node_route_results -->|"requests routes"| node_route_service
node_route_page -->|"searches routes"| node_route_service
node_drive_page -->|"uses"| node_drive_state
node_drive_state -->|"creates trips and events"| node_route_service
node_drive_state -->|"saves completed trips"| node_history_service
node_drive_state -->|"persists state"| node_storage
node_replay -->|"loads history"| node_history_service
node_profile -->|"loads and saves profile"| node_profile_service
node_profile -->|"stores preferences"| node_storage
node_forecast_service -->|"requests data"| node_api_client
node_route_service -->|"requests routes and trips"| node_api_client
node_history_service -->|"requests history"| node_api_client
node_profile_service -->|"requests profile"| node_api_client
node_api_client -->|"calls API"| node_api_server
node_api_server -->|"mounts router"| node_forecast_api
node_api_server -->|"mounts router"| node_places_api
node_api_server -->|"mounts router"| node_routes_api
node_api_server -->|"mounts router"| node_profile_api
node_api_server -->|"mounts router"| node_trips_api
node_forecast_api -->|"reads examples"| node_zones
node_places_api -->|"reads examples"| node_places
node_routes_api -->|"selects candidates"| node_places
node_routes_api -->|"reads hourly rates"| node_zones
node_routes_api -->|"gets directions"| node_kakao
node_routes_api -->|"validates route data"| node_route_schema
node_profile_api -->|"validates user"| node_auth_guard
node_trips_api -->|"validates user"| node_auth_guard
node_auth_guard -->|"checks token"| node_supabase_client
node_profile_api -->|"reads and writes profile"| node_supabase_client
node_trips_api -->|"uses database client"| node_supabase_client

click node_app "https://github.com/gdg-cnu/netradar/blob/main/front/src/App.tsx"
click node_login "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/LoginPage.tsx"
click node_forecast "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/MapPage.tsx"
click node_forecast_ui "https://github.com/gdg-cnu/netradar/tree/main/front/src/components/map"
click node_route_page "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/RoutePage.tsx"
click node_place_search "https://github.com/gdg-cnu/netradar/blob/main/front/src/components/route/PlaceSearch.tsx"
click node_route_results "https://github.com/gdg-cnu/netradar/blob/main/front/src/components/route/RouteResults.tsx"
click node_drive_page "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/DrivePage.tsx"
click node_drive_state "https://github.com/gdg-cnu/netradar/blob/main/front/src/hooks/useDrive.ts"
click node_replay "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/ReplayPage.tsx"
click node_profile "https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/MyPage.tsx"
click node_api_client "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/api.ts"
click node_route_service "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/routes.ts"
click node_forecast_service "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/forecast.ts"
click node_profile_service "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/profile.ts"
click node_history_service "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/history.ts"
click node_storage "https://github.com/gdg-cnu/netradar/blob/main/front/src/utils/storage.ts"
click node_session "https://github.com/gdg-cnu/netradar/blob/main/front/src/hooks/useAppSession.ts"
click node_supabase_auth "https://github.com/gdg-cnu/netradar/blob/main/front/src/services/auth.ts"
click node_api_server "https://github.com/gdg-cnu/netradar/blob/main/backend/main.py"
click node_forecast_api "https://github.com/gdg-cnu/netradar/blob/main/backend/routers/forecast.py"
click node_places_api "https://github.com/gdg-cnu/netradar/blob/main/backend/routers/places.py"
click node_routes_api "https://github.com/gdg-cnu/netradar/blob/main/backend/routers/routes.py"
click node_profile_api "https://github.com/gdg-cnu/netradar/blob/main/backend/routers/profile.py"
click node_trips_api "https://github.com/gdg-cnu/netradar/blob/main/backend/routers/trips.py"
click node_zones "https://github.com/gdg-cnu/netradar/blob/main/backend/data/mock_zones.py"
click node_places "https://github.com/gdg-cnu/netradar/blob/main/backend/data/mock_places.py"
click node_route_schema "https://github.com/gdg-cnu/netradar/blob/main/backend/schemas/route.py"
click node_supabase_client "https://github.com/gdg-cnu/netradar/blob/main/backend/db/client.py"
click node_auth_guard "https://github.com/gdg-cnu/netradar/blob/main/backend/db/auth.py"
click node_kakao "https://github.com/gdg-cnu/netradar/blob/main/backend/kakao_mobility.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_login,node_forecast,node_forecast_ui,node_route_page,node_place_search,node_route_results,node_drive_page,node_drive_state,node_replay,node_profile,node_api_client,node_route_service,node_forecast_service,node_profile_service,node_history_service toneBlue
class node_api_server,node_forecast_api,node_places_api,node_routes_api,node_profile_api,node_trips_api,node_route_schema toneAmber
class node_zones,node_places toneMint
class node_storage,node_session,node_supabase_client,node_auth_guard toneRose
class node_supabase_auth,node_kakao,node_driver toneIndigo
```

## Components

### Driver app

- [App shell](https://github.com/gdg-cnu/netradar/blob/main/front/src/App.tsx): `front/src/App.tsx`
- [Login](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/LoginPage.tsx): `front/src/pages/LoginPage.tsx`
- [Earnings map](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/MapPage.tsx): `front/src/pages/MapPage.tsx`
- [Forecast views](https://github.com/gdg-cnu/netradar/tree/main/front/src/components/map): `front/src/components/map`
- [Route planning](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/RoutePage.tsx): `front/src/pages/RoutePage.tsx`
- [Place search](https://github.com/gdg-cnu/netradar/blob/main/front/src/components/route/PlaceSearch.tsx): `front/src/components/route/PlaceSearch.tsx`
- [Route results](https://github.com/gdg-cnu/netradar/blob/main/front/src/components/route/RouteResults.tsx): `front/src/components/route/RouteResults.tsx`
- [Drive guidance](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/DrivePage.tsx): `front/src/pages/DrivePage.tsx`
- [Drive state](https://github.com/gdg-cnu/netradar/blob/main/front/src/hooks/useDrive.ts): `front/src/hooks/useDrive.ts`
- [Trip replay](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/ReplayPage.tsx): `front/src/pages/ReplayPage.tsx`
- [Profile](https://github.com/gdg-cnu/netradar/blob/main/front/src/pages/MyPage.tsx): `front/src/pages/MyPage.tsx`
- [API client](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/api.ts): `front/src/services/api.ts`
- [Route service](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/routes.ts): `front/src/services/routes.ts`
- [Forecast service](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/forecast.ts): `front/src/services/forecast.ts`
- [Profile service](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/profile.ts): `front/src/services/profile.ts`
- [History service](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/history.ts): `front/src/services/history.ts`

### FastAPI services

- [FastAPI app](https://github.com/gdg-cnu/netradar/blob/main/backend/main.py): `backend/main.py`
- [Forecast endpoint](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/forecast.py): `backend/routers/forecast.py`
- [Places endpoint](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/places.py): `backend/routers/places.py`
- [Recommendations](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/routes.py): `backend/routers/routes.py`
- [Profile endpoint](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/profile.py): `backend/routers/profile.py`
- [Trip events](https://github.com/gdg-cnu/netradar/blob/main/backend/routers/trips.py): `backend/routers/trips.py`
- [Route contracts](https://github.com/gdg-cnu/netradar/blob/main/backend/schemas/route.py): `backend/schemas/route.py`

### Backend data

- [Sample zones](https://github.com/gdg-cnu/netradar/blob/main/backend/data/mock_zones.py): `backend/data/mock_zones.py`
- [Sample places](https://github.com/gdg-cnu/netradar/blob/main/backend/data/mock_places.py): `backend/data/mock_places.py`

### Identity and storage

- [Browser storage](https://github.com/gdg-cnu/netradar/blob/main/front/src/utils/storage.ts): `front/src/utils/storage.ts`
- [Session state](https://github.com/gdg-cnu/netradar/blob/main/front/src/hooks/useAppSession.ts): `front/src/hooks/useAppSession.ts`
- [Supabase client](https://github.com/gdg-cnu/netradar/blob/main/backend/db/client.py): `backend/db/client.py`
- [Token validation](https://github.com/gdg-cnu/netradar/blob/main/backend/db/auth.py): `backend/db/auth.py`

### External providers

- [Supabase auth](https://github.com/gdg-cnu/netradar/blob/main/front/src/services/auth.ts): `front/src/services/auth.ts`
- [Kakao Mobility](https://github.com/gdg-cnu/netradar/blob/main/backend/kakao_mobility.py): `backend/kakao_mobility.py`

### Other components

- **Taxi driver**

## Connections

- Taxi driver → App shell: opens (evidence: `front/src/App.tsx`)
- App shell → Session state: checks session (evidence: `front/src/App.tsx`)
- App shell → Login: shows when signed out (evidence: `front/src/App.tsx`)
- App shell → Earnings map: routes to (evidence: `front/src/App.tsx`)
- App shell → Route planning: routes to (evidence: `front/src/App.tsx`)
- App shell → Drive guidance: routes to (evidence: `front/src/App.tsx`)
- App shell → Trip replay: routes to (evidence: `front/src/App.tsx`)
- App shell → Profile: routes to (evidence: `front/src/App.tsx`)
- Session state → Supabase auth: reads session (evidence: `front/src/hooks/useAppSession.ts`)
- Session state → Browser storage: sets account scope (evidence: `front/src/hooks/useAppSession.ts`)
- Login → Supabase auth: authenticates (evidence: `front/src/pages/LoginPage.tsx`)
- Earnings map → Forecast views: renders (evidence: `front/src/pages/MapPage.tsx`)
- Earnings map → Forecast service: loads forecasts (evidence: `front/src/pages/MapPage.tsx`)
- Route planning → Place search: uses (evidence: `front/src/pages/RoutePage.tsx`)
- Route planning → Route results: renders (evidence: `front/src/pages/RoutePage.tsx`)
- Route results → Route service: requests routes (evidence: `front/src/components/route/RouteResults.tsx`)
- Route planning → Route service: searches routes (evidence: `front/src/pages/RoutePage.tsx`)
- Drive guidance → Drive state: uses (evidence: `front/src/pages/DrivePage.tsx`)
- Drive state → Route service: creates trips and events (evidence: `front/src/hooks/useDrive.ts`)
- Drive state → History service: saves completed trips (evidence: `front/src/hooks/useDrive.ts`)
- Drive state → Browser storage: persists state (evidence: `front/src/hooks/useDrive.ts`)
- Trip replay → History service: loads history (evidence: `front/src/pages/ReplayPage.tsx`)
- Profile → Profile service: loads and saves profile (evidence: `front/src/pages/MyPage.tsx`)
- Profile → Browser storage: stores preferences (evidence: `front/src/pages/MyPage.tsx`)
- Forecast service → API client: requests data (evidence: `front/src/pages/MapPage.tsx`)
- Route service → API client: requests routes and trips (evidence: `front/src/services/routes.ts`)
- History service → API client: requests history (evidence: `front/src/services/history.ts`)
- Profile service → API client: requests profile (evidence: `front/src/pages/MyPage.tsx`)
- API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Forecast endpoint: mounts router (evidence: `backend/main.py`)
- FastAPI app → Places endpoint: mounts router (evidence: `backend/main.py`)
- FastAPI app → Recommendations: mounts router (evidence: `backend/main.py`)
- FastAPI app → Profile endpoint: mounts router (evidence: `backend/main.py`)
- FastAPI app → Trip events: mounts router (evidence: `backend/main.py`)
- Forecast endpoint → Sample zones: reads examples (evidence: `backend/routers/forecast.py`)
- Places endpoint → Sample places: reads examples (evidence: `backend/routers/places.py`)
- Recommendations → Sample places: selects candidates (evidence: `backend/routers/routes.py`)
- Recommendations → Sample zones: reads hourly rates (evidence: `backend/routers/routes.py`)
- Recommendations → Kakao Mobility: gets directions (evidence: `backend/routers/routes.py`)
- Recommendations → Route contracts: validates route data (evidence: `backend/routers/routes.py`)
- Profile endpoint → Token validation: validates user (evidence: `backend/routers/profile.py`)
- Trip events → Token validation: validates user (evidence: `backend/routers/trips.py`)
- Token validation → Supabase client: checks token (evidence: `backend/db/auth.py`)
- Profile endpoint → Supabase client: reads and writes profile (evidence: `backend/routers/profile.py`)
- Trip events → Supabase client: uses database client (evidence: `backend/routers/trips.py`)
