Akiba So
e22b004f9e
Migrate maps to @geoscene/core, polish monitoring/alerts UX, fix timeline basemap flicker and district alert regions, and ship compose/nginx Docker deploy assets with CBPOA_ROOT data mounts. Co-authored-by: Cursor <cursoragent@cursor.com>
59 lines
2.0 KiB
Markdown
59 lines
2.0 KiB
Markdown
# Frontend — React + TypeScript + GeoScene Maps SDK
|
|
|
|
## Stack
|
|
|
|
- React 18, TypeScript 5, Vite 5
|
|
- Tailwind CSS, Recharts, Zustand (state), Axios
|
|
- `@geoscene/core` (Maps SDK for JavaScript) — POC uses Tianditu basemap + local GeoJSON / FastAPI risk tiles
|
|
- Playwright (e2e tests)
|
|
|
|
## Structure
|
|
|
|
```
|
|
frontend/src/
|
|
main.tsx # Entry (+ GeoScene theme CSS)
|
|
App.tsx # Router setup
|
|
geoscene/ # MapView helpers + layer factories
|
|
components/ # Reusable UI (maps, charts, nav)
|
|
legacy/ # Unused former Leaflet map experiments
|
|
pages/ # Route-level views
|
|
services/api.ts # Axios client with TTL cache + request dedup
|
|
stores/ # Zustand stores
|
|
types/index.ts # Shared TypeScript interfaces
|
|
utils/ # Helpers (responsive.ts)
|
|
```
|
|
|
|
## Path Alias
|
|
|
|
`@/` maps to `src/` — use `import { X } from '@/components/X'`.
|
|
|
|
## Patterns
|
|
|
|
- Components: PascalCase, one per file, default export
|
|
- Map components: imperative `@geoscene/core` via `createMapView` — do not pass MapView instances between components
|
|
- Coordinates: GeoScene uses `[longitude, latitude]`
|
|
- API calls: use `services/api.ts` wrappers (`riskApi`, `alertApi`, `caseApi`, `gridApi`)
|
|
- State: Zustand stores in `stores/`
|
|
- Styling: Tailwind utility classes
|
|
|
|
## Env (optional Enterprise later)
|
|
|
|
See `.env.example` for `VITE_GEOSCENE_PORTAL_URL` / `VITE_LAYER_*`. POC runs without them.
|
|
|
|
## Running
|
|
|
|
```bash
|
|
cd frontend
|
|
pnpm dev # localhost:3000, proxies /api → localhost:8000
|
|
pnpm build # tsc + vite build → dist/
|
|
```
|
|
|
|
## Anti-Patterns
|
|
|
|
- Don't call axios directly — use the cached API wrappers in `services/api.ts`
|
|
- Don't use `any` in TypeScript types — use `unknown` and narrow
|
|
- Don't mix data fetching with presentation — fetch in pages, render in components
|
|
- Don't inline styles when Tailwind classes work
|
|
- Don't create god components (>200 lines) — extract sub-components
|
|
- Don't reintroduce Leaflet or role/perspective switchers
|