# lju0302/webui architecture

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

- Interactive diagram: https://gitdiagram.com/lju0302/webui
- Repository: https://github.com/lju0302/webui

## Overview

1. **Repo shape**
   - This is a split full-stack monorepo: a **React + TypeScript + Vite** frontend at the root and a **FastAPI / Python 3.11** backend in `backend/`.
   - The product is a **biosecurity route-dispatch system** for livestock disease prevention, centered on farm visits, risk-based routing, and operational tracking.

2. **Primary user-facing surfaces**
   - The frontend is organized by operational views: **map**, **dispatch**, **confirmed route**, **mobile field**, and **login** pages.
   - The main UI is a map-driven control panel for planners, plus a lighter mobile workflow for field teams.

3. **Frontend state and composition**
   - Global state is split into Zustand stores for **auth, dispatch, emergency mode, facilities, farm data, and outbreak alerts**.
   - Components are grouped by responsibility: layout shell, map controls/legend, farm detail overlays, dispatch result/settings, and route/team cards.

4. **Map subsystem**
   - The app uses **Naver Maps JavaScript API** on the frontend, with a dedicated script-loading hook and map-specific components.
   - Map behavior is an important boundary: the browser renders map layers and interactive overlays, while route calculation is delegated to backend APIs.

5. **Frontend API boundary**
   - The `src/api/*` layer is the typed client boundary between the UI and backend.
   - Calls are organized by domain: **farms, facilities, directions, dispatch, alerts**. This keeps UI components from talking directly to server details.

6. **Backend API layer**
   - FastAPI routers mirror the same domains: `farms.py`, `facilities.py`, `directions.py`, `dispatch.py`, and `alerts.py`.
   - This suggests a clean service API for the frontend rather than a monolithic endpoint surface.

7. **Core backend services**
   - Business logic lives under `backend/services/`, especially **dispatch optimization**, **dispatch constraints**, **disinfection facility handling**, and client wrappers for external systems.
   - The backend is not just a CRUD API; it contains the route-planning engine and the integration layer to external data/routing services.

8. **Routing and optimization flow**
   - The key workflow is: **farm/risk data → constraints → route optimization → dispatch result**.
   - `dispatch_optimizer.py` and `dispatch_constraints.py` indicate that assignment and sequencing are computed server-side, then returned to the frontend for visualization and operational use.

9. **External integrations**
   - The backend wraps several external dependencies: **Naver** services, **OSRM** for routing, **Databricks** for analytics/ML-style data access, and a database via `db.py`.
   - The presence of both `naver_client.py` and `osrm_client.py` implies the system can combine map/routing providers or use one as fallback/alternative.

10. **Data sources and domain data**
   - Farm and facility information is likely sourced from the backend database and static reference data, including the CSV file for **disinfection facilities**.
   - The frontend also contains `mockFarms.ts`, which suggests local demo/mock data support for development or fallback scenarios.

11. **Operational alerting and emergency mode**
   - `alerts` and `outbreak` stores/components indicate a live operational layer for **outbreak alerts** and **emergency mode** presentation.
   - The UI includes banners for data source status and emergency mode, so the architecture supports real-time operational context, not just static route planning.

12. **Experimental algorithms are isolated**
   - `backend/services/experiments/` contains alternate optimization and clustering approaches, including ALNS and risk-clustering variants.
   - These appear to be research/prototyping code paths kept separate from the main production dispatch flow.

13. **Deployment boundary**
   - The repository is designed for **Azure App Service** deployment on the backend side, with environment-driven secrets for Naver and Databricks.
   - The frontend expects `VITE_API_BASE_URL` to point at the backend API, so browser access and server deployment are separated by configuration.

14. **How to draw the architecture**
   - A good diagram would show: **operator/mobile browser → React UI → typed API clients → FastAPI routers → service layer → external routing/data providers + database**.
   - Side domains to show explicitly are **map rendering**, **dispatch optimization**, **alert/emergency state**, and **facility/farm data management**.

Main entry points: [`src/App.tsx`](https://github.com/lju0302/webui/blob/main/src/App.tsx) (App routes), [`backend/routers/dispatch.py`](https://github.com/lju0302/webui/blob/main/backend/routers/dispatch.py) (API routers), [`src/pages/MapPage.tsx`](https://github.com/lju0302/webui/blob/main/src/pages/MapPage.tsx) (Map page), [`src/store/useDispatchStore.ts`](https://github.com/lju0302/webui/blob/main/src/store/useDispatchStore.ts) (Client state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_main["App shell<br/>React entry<br/>[main.tsx]"]
  node_src_app["App routes<br/>React router<br/>[App.tsx]"]
  node_page_map["Map page<br/>Operator UI<br/>[MapPage.tsx]"]
  node_page_dispatch["Dispatch page<br/>Planner UI<br/>[DispatchPage.tsx]"]
  node_page_route["Confirmed route<br/>Route UI"]
  node_page_mobile["Mobile field<br/>Field UI"]
  node_page_login["Login<br/>Auth UI<br/>[LoginPage.tsx]"]
  node_naver_map["Naver map<br/>Map widget<br/>[NaverMap.tsx]"]
  node_map_script["Map loader<br/>Hook"]
  node_dispatch_views["Dispatch views<br/>UI components"]
  node_farm_detail["Farm details<br/>Overlay components"]
  node_mobile_card["Visit card<br/>Mobile component<br/>[FarmVisitCard.tsx]"]
  node_frontend_store["Client state<br/>Zustand stores"]
  node_api_client["Typed API<br/>Frontend boundary<br/>[dispatch.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>API entry<br/>[main.py]"]
  node_backend_routes["API routers<br/>[dispatch.py]"]
  node_dispatch_service["Dispatch engine<br/>Optimization services"]
  node_facility_service["Facility data<br/>Domain services"]
  node_external_clients["External clients<br/>Integrations<br/>[naver_client.py]"]
end

subgraph group_integrations["External Systems"]
end

node_src_main -->|"renders"| node_src_app
node_src_app -->|"routes to"| node_page_map
node_src_app -->|"routes to"| node_page_dispatch
node_src_app -->|"routes to"| node_page_route
node_src_app -->|"routes to"| node_page_mobile
node_src_app -->|"routes to"| node_page_login
node_page_map -->|"uses"| node_naver_map
node_naver_map -->|"loads via"| node_map_script
node_page_map -->|"shows"| node_farm_detail
node_page_dispatch -->|"uses"| node_dispatch_views
node_page_mobile -->|"uses"| node_mobile_card
node_page_route -->|"renders on"| node_naver_map
node_frontend_store -->|"feeds"| node_page_map
node_frontend_store -->|"feeds"| node_page_dispatch
node_frontend_store -->|"feeds"| node_page_mobile
node_api_client -->|"calls"| node_backend_routes
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_dispatch_service
node_backend_routes -->|"delegates"| node_facility_service
node_dispatch_service -->|"uses"| node_external_clients
node_facility_service -->|"uses"| node_external_clients
node_backend_routes -->|"reads/writes"| node_external_clients

click node_src_main "https://github.com/lju0302/webui/blob/main/src/main.tsx"
click node_src_app "https://github.com/lju0302/webui/blob/main/src/App.tsx"
click node_page_map "https://github.com/lju0302/webui/blob/main/src/pages/MapPage.tsx"
click node_page_dispatch "https://github.com/lju0302/webui/blob/main/src/pages/DispatchPage.tsx"
click node_page_route "https://github.com/lju0302/webui/blob/main/src/pages/ConfirmedRoutePage.tsx"
click node_page_mobile "https://github.com/lju0302/webui/blob/main/src/pages/MobileFieldPage.tsx"
click node_page_login "https://github.com/lju0302/webui/blob/main/src/pages/LoginPage.tsx"
click node_naver_map "https://github.com/lju0302/webui/blob/main/src/components/map/NaverMap.tsx"
click node_map_script "https://github.com/lju0302/webui/blob/main/src/hooks/useNaverMapsScript.ts"
click node_dispatch_views "https://github.com/lju0302/webui/blob/main/src/components/dispatch/DispatchResultView.tsx"
click node_farm_detail "https://github.com/lju0302/webui/blob/main/src/components/detail/FarmDetailOverlay.tsx"
click node_mobile_card "https://github.com/lju0302/webui/blob/main/src/components/mobile/FarmVisitCard.tsx"
click node_frontend_store "https://github.com/lju0302/webui/blob/main/src/store/useDispatchStore.ts"
click node_api_client "https://github.com/lju0302/webui/blob/main/src/api/dispatch.ts"
click node_backend_main "https://github.com/lju0302/webui/blob/main/backend/main.py"
click node_backend_routes "https://github.com/lju0302/webui/blob/main/backend/routers/dispatch.py"
click node_dispatch_service "https://github.com/lju0302/webui/blob/main/backend/services/dispatch_optimizer.py"
click node_facility_service "https://github.com/lju0302/webui/blob/main/backend/services/disinfection_facilities.py"
click node_external_clients "https://github.com/lju0302/webui/blob/main/backend/services/naver_client.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_src_main,node_src_app,node_page_map,node_page_dispatch,node_page_route,node_page_mobile,node_page_login,node_naver_map,node_map_script,node_dispatch_views,node_farm_detail,node_mobile_card,node_frontend_store,node_api_client toneBlue
class node_backend_main,node_backend_routes,node_dispatch_service,node_facility_service,node_external_clients toneAmber
```

## Components

### Frontend

React + TypeScript UI, map-driven dispatch workspace, and client-side state

- [App shell](https://github.com/lju0302/webui/blob/main/src/main.tsx): React entry · Bootstraps the Vite app and top-level routing/layout composition · `src/main.tsx`
- [App routes](https://github.com/lju0302/webui/blob/main/src/App.tsx): React router · Chooses the main operational pages and ties them into the layout · `src/App.tsx`
- [Map page](https://github.com/lju0302/webui/blob/main/src/pages/MapPage.tsx): Operator UI · Primary planner workspace centered on map-driven dispatch operations · `src/pages/MapPage.tsx`
- [Dispatch page](https://github.com/lju0302/webui/blob/main/src/pages/DispatchPage.tsx): Planner UI · Workflow for building and reviewing dispatch results and settings · `src/pages/DispatchPage.tsx`
- [Confirmed route](https://github.com/lju0302/webui/blob/main/src/pages/ConfirmedRoutePage.tsx): Route UI · Operational view for finalized routes and team assignment status · `src/pages/ConfirmedRoutePage.tsx`
- [Mobile field](https://github.com/lju0302/webui/blob/main/src/pages/MobileFieldPage.tsx): Field UI · Lightweight field workflow for farm visits and mobile use · `src/pages/MobileFieldPage.tsx`
- [Login](https://github.com/lju0302/webui/blob/main/src/pages/LoginPage.tsx): Auth UI · Authentication entry point for operators · `src/pages/LoginPage.tsx`
- [Naver map](https://github.com/lju0302/webui/blob/main/src/components/map/NaverMap.tsx): Map widget · Browser map rendering surface for layers, markers, and overlays · `src/components/map/NaverMap.tsx`
- [Map loader](https://github.com/lju0302/webui/blob/main/src/hooks/useNaverMapsScript.ts): Hook · Loads the Naver Maps JavaScript API into the browser · `src/hooks/useNaverMapsScript.ts`
- [Dispatch views](https://github.com/lju0302/webui/blob/main/src/components/dispatch/DispatchResultView.tsx): UI components · Result and settings panels used to inspect and tune dispatch output · `src/components/dispatch/DispatchResultView.tsx`
- [Farm details](https://github.com/lju0302/webui/blob/main/src/components/detail/FarmDetailOverlay.tsx): Overlay components · Farm detail panel and overlay shown on top of the map · `src/components/detail/FarmDetailOverlay.tsx`
- [Visit card](https://github.com/lju0302/webui/blob/main/src/components/mobile/FarmVisitCard.tsx): Mobile component · Per-farm mobile visit card for field workflow · `src/components/mobile/FarmVisitCard.tsx`
- [Client state](https://github.com/lju0302/webui/blob/main/src/store/useDispatchStore.ts): Zustand stores · Auth, dispatch, emergency, facilities, farm, and outbreak state in the browser · `src/store/useDispatchStore.ts`
- [Typed API](https://github.com/lju0302/webui/blob/main/src/api/dispatch.ts): Frontend boundary · Domain-specific client layer for farms, facilities, directions, dispatch, and alerts · `src/api/dispatch.ts`

### Backend

FastAPI service layer, optimization logic, and data access

- [FastAPI app](https://github.com/lju0302/webui/blob/main/backend/main.py): API entry · Backend application bootstrap and router registration · `backend/main.py`
- [API routers](https://github.com/lju0302/webui/blob/main/backend/routers/dispatch.py): FastAPI routers · Domain routers for farms, facilities, directions, dispatch, and alerts · `backend/routers/dispatch.py`
- [Dispatch engine](https://github.com/lju0302/webui/blob/main/backend/services/dispatch_optimizer.py): Optimization services · Server-side constraints and route optimization for dispatch planning · `backend/services/dispatch_optimizer.py`
- [Facility data](https://github.com/lju0302/webui/blob/main/backend/services/disinfection_facilities.py): Domain services · Disinfection facility handling and farm/facility data shaping · `backend/services/disinfection_facilities.py`
- [External clients](https://github.com/lju0302/webui/blob/main/backend/services/naver_client.py): Integrations · Wrappers for Naver, OSRM, Databricks, outbreak feeds, and database access · `backend/services/naver_client.py`

## Connections

- App shell → App routes: renders · Application entry mounts the routed app shell
- App routes → Map page: routes to · Opens the map-centric planner surface
- App routes → Dispatch page: routes to · Opens the dispatch workflow
- App routes → Confirmed route: routes to · Opens confirmed route operations
- App routes → Mobile field: routes to · Opens the field mobile workflow
- App routes → Login: routes to · Opens authentication
- Map page → Naver map: uses · Map page composes the interactive map surface
- Naver map → Map loader: loads via · Map widget depends on browser script injection
- Map page → Farm details: shows · Map page surfaces farm detail overlays
- Dispatch page → Dispatch views: uses · Dispatch page renders settings and results panels
- Mobile field → Visit card: uses · Mobile view centers on farm visit cards
- Confirmed route → Naver map: renders on · Confirmed route view uses map visualization for route context
- Client state → Map page: feeds · Map interactions depend on shared client state
- Client state → Dispatch page: feeds · Dispatch workflow reads and writes shared state
- Client state → Mobile field: feeds · Field workflow consumes auth, farm, and route state
- Typed API → API routers: calls · Typed frontend client is the boundary to backend APIs
- FastAPI app → API routers: mounts · FastAPI app registers the domain routers
- API routers → Dispatch engine: delegates · Dispatch endpoints invoke optimization logic
- API routers → Facility data: delegates · Farm and facility endpoints use domain data services
- Dispatch engine → External clients: uses · Optimization relies on routing, analytics, and database integrations
- Facility data → External clients: uses · Facility and farm data services use shared external access layers
- API routers → External clients: reads/writes · Routers ultimately depend on underlying data and provider clients
