How lju0302/webui works
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: App.tsx App routes · dispatch.py API routers · MapPage.tsx Map page · useDispatchStore.ts Client state
Components 19
Frontend
React + TypeScript UI, map-driven dispatch workspace, and client-side state
- App shell · Bootstraps the Vite app and top-level routing/layout composition
src/main.tsx - App routes · Chooses the main operational pages and ties them into the layout
src/App.tsx - Map page · Primary planner workspace centered on map-driven dispatch operations
src/pages/MapPage.tsx - Dispatch page · Workflow for building and reviewing dispatch results and settings
src/pages/DispatchPage.tsx - Confirmed route · Operational view for finalized routes and team assignment status
src/pages/ConfirmedRoutePage.tsx - Mobile field · Lightweight field workflow for farm visits and mobile use
src/pages/MobileFieldPage.tsx - Login · Authentication entry point for operators
src/pages/LoginPage.tsx - Naver map · Browser map rendering surface for layers, markers, and overlays
src/components/map/NaverMap.tsx - Map loader · Loads the Naver Maps JavaScript API into the browser
src/hooks/useNaverMapsScript.ts - Dispatch views · Result and settings panels used to inspect and tune dispatch output
src/components/dispatch/DispatchResultView.tsx - Farm details · Farm detail panel and overlay shown on top of the map
src/components/detail/FarmDetailOverlay.tsx - Visit card · Per-farm mobile visit card for field workflow
src/components/mobile/FarmVisitCard.tsx - Client state · Auth, dispatch, emergency, facilities, farm, and outbreak state in the browser
src/store/useDispatchStore.ts - Typed API · 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 · Backend application bootstrap and router registration
backend/main.py - API routers · Domain routers for farms, facilities, directions, dispatch, and alerts
backend/routers/dispatch.py - Dispatch engine · Server-side constraints and route optimization for dispatch planning
backend/services/dispatch_optimizer.py - Facility data · Disinfection facility handling and farm/facility data shaping
backend/services/disinfection_facilities.py - External clients · Wrappers for Naver, OSRM, Databricks, outbreak feeds, and database access
backend/services/naver_client.py
Connections 22
- 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