fix: restore GeoIntel and upgrade Atlas workbench
This commit is contained in:
Jens
+134
-31
@@ -1,45 +1,148 @@
|
||||
# DockDeck architecture
|
||||
# Architecture
|
||||
|
||||
## Runtime
|
||||
## 1. Overzicht
|
||||
|
||||
DockDeck is one deployable Node.js process. Fastify owns the REST API and serves the compiled React client in production. React/Vite provides the development UI. SQLite is mounted at `/data`; Drizzle ORM owns typed reads and writes while a small idempotent SQL migration creates the first schema before Fastify starts.
|
||||
GeoIntel bestaat uit:
|
||||
|
||||
- React/TypeScript frontend
|
||||
- FastAPI backend
|
||||
- PostgreSQL/PostGIS database
|
||||
- background job queue
|
||||
- file/object storage
|
||||
- GIS processing services
|
||||
- AI inference services
|
||||
|
||||
## 2. Hoofdcomponenten
|
||||
|
||||
```text
|
||||
Browser → Fastify API → domain rules → Drizzle → SQLite
|
||||
↘ discovery service → AppOps inventory (GET only)
|
||||
→ Unraid XML/runtime mounts (read only)
|
||||
→ NPM API (read only, optional)
|
||||
Frontend
|
||||
↓ REST/WebSocket
|
||||
FastAPI Backend
|
||||
↓
|
||||
PostgreSQL + PostGIS
|
||||
↓
|
||||
Storage: uploads, processed rasters, tiles, masks, exports
|
||||
↓
|
||||
Workers: GIS processing, AI inference, QA/QC, export
|
||||
```
|
||||
|
||||
## Trust boundaries
|
||||
## 3. Frontend
|
||||
|
||||
- The `dockdeck` container never receives `/var/run/docker.sock`.
|
||||
- The standard deployment is exactly one `DockDeck` container. A separate `dockerproxy` exists only in the optional fallback overlay; there it is private, has `POST=0` and disables all mutation families.
|
||||
- Unraid templates are mounted read-only.
|
||||
- NPM, Gitea and provider credentials exist only as server-side process environment. Values entered in Settings are persisted in the permission-restricted environment file and remain excluded from API responses, SQLite and JSON exports.
|
||||
- Fastify validates every user-controlled mutation with Zod. External integration errors are reduced to non-sensitive connection states.
|
||||
- New discoveries are inserted with `visible=false`. Subsequent syncs update runtime fields but preserve user choices and overrides.
|
||||
- A DockDeck-only app removal records the technical name in `removed_apps`; later discovery ignores that name and never calls a Docker mutation endpoint.
|
||||
Aanbevolen stack:
|
||||
|
||||
## Modules
|
||||
- React
|
||||
- TypeScript
|
||||
- MapLibre GL
|
||||
- Deck.gl
|
||||
- Tailwind
|
||||
- TanStack Query
|
||||
- Zustand of vergelijkbare lichte state store
|
||||
- Recharts voor eenvoudige grafieken
|
||||
|
||||
- `src/shared`: Zod contracts and pure URL/search/matching/sorting rules.
|
||||
- URL resolution prefers an explicit `br0` LAN address, then the configured Unraid host, and uses a single unambiguous published TCP port when template metadata is stale.
|
||||
- Dashboard search is a derived client index over the latest payload, so renames, removals, category changes and URL changes require no separate search persistence.
|
||||
- `src/server/database.ts`: persistence, migration, import/export and user preference invariants.
|
||||
- Widget layout is stored as validated size/content, metric order/visibility/style, statistic limit, warning and chart fields on app and preference records. Legacy rows receive safe standard/all-content defaults; version 1 backups remain compatible because added backup fields are optional on import.
|
||||
- `src/server/integrations`: read-only external adapters, provider capability metadata and deterministic mocks. Provider URLs default to an already discovered local app origin; explicit environment overrides remain available. Provider recognition is token-based and excludes known support-container roles.
|
||||
- `src/server/integrations/unraid-status.ts`: parseert een minimale read-only view van Unraid runtime- en hwmondata naar array-, parity-, opslag-, temperatuur- en optionele UPS-metrics.
|
||||
- Provideradapters bewaren alleen de laatst succesvolle gereduceerde metricresponse en een korte tijdreeks in procesgeheugen; geen van beide overleeft een procesrestart.
|
||||
- `src/server/app.ts`: narrow REST surface; no Docker control routes.
|
||||
- `src/client`: accessible responsive UI and design tokens.
|
||||
Belangrijke principes:
|
||||
|
||||
## Layout and offline model
|
||||
- kaart centraal, maar analysepanelen even belangrijk
|
||||
- labs per workflow
|
||||
- duidelijke jobstatus
|
||||
- outputs altijd exporteerbaar
|
||||
- geen verborgen mockgedrag
|
||||
|
||||
Widgetvolgorde staat los van apptegelvolgorde. App- en hostrecords bewaren hun eigen volgorde; layoutpresets bevatten alleen presentatievelden, inclusief metricselectie, value/gauge/progress, waarschuwing en lijn-/vlak-/staafgrafiek. Provider- en hosthistoriek bevat maximaal zestig punten per numerieke reeks en blijft uitsluitend in procesgeheugen. Het toepassen van een preset kan geen appzichtbaarheid, navigatie-URL, credential of Dockerstaat wijzigen.
|
||||
## 4. Backend
|
||||
|
||||
De serviceworker cachet alleen statische applicatieshellassets. Requests onder `/api/` worden volledig overgeslagen, zodat offline content nooit als actuele runtime- of providerdata wordt gepresenteerd.
|
||||
Aanbevolen stack:
|
||||
|
||||
## Failure behavior
|
||||
- FastAPI
|
||||
- SQLAlchemy 2.x
|
||||
- GeoAlchemy2
|
||||
- Alembic
|
||||
- Pydantic
|
||||
- RQ/Celery
|
||||
- Rasterio
|
||||
- GeoPandas
|
||||
- Shapely
|
||||
- PyProj
|
||||
- NumPy
|
||||
- OpenCV
|
||||
- Ultralytics/PyTorch
|
||||
|
||||
Saved data is always returned independently of integration health. A failed AppOps inventory, missing Unraid mount or unavailable NPM instance produces a degraded integration card/banner without blocking navigation. Polling runs only while the browser tab is visible. AppOps inventory is read immediately; its slower all-container resource sample refreshes in the background so it cannot delay navigation.
|
||||
## 5. Database
|
||||
|
||||
PostgreSQL met PostGIS is verplicht voor:
|
||||
|
||||
- projectgebieden
|
||||
- vectorfeatures
|
||||
- detectiepolygonen
|
||||
- segmentatiepolygonen
|
||||
- spatial joins
|
||||
- intersects
|
||||
- IoU berekeningen
|
||||
- bounds queries
|
||||
|
||||
## 6. Storage
|
||||
|
||||
Bewaar grote bestanden niet in de database.
|
||||
|
||||
Opslagcategorieën:
|
||||
|
||||
- originele uploads
|
||||
- verwerkte rasters
|
||||
- raster tiles
|
||||
- masks
|
||||
- model outputs
|
||||
- exports
|
||||
- rapporten
|
||||
|
||||
Database bewaart metadata en paden.
|
||||
|
||||
## 7. Jobs
|
||||
|
||||
Langlopende processen moeten via background jobs:
|
||||
|
||||
- raster metadata extraction
|
||||
- raster clipping
|
||||
- raster tiling
|
||||
- vector import
|
||||
- AI inference
|
||||
- segmentation polygonize
|
||||
- QA/QC
|
||||
- change detection
|
||||
- export generation
|
||||
|
||||
## 8. AI Inference
|
||||
|
||||
Inference pipeline:
|
||||
|
||||
```text
|
||||
Raster dataset
|
||||
→ clip to area
|
||||
→ tile raster
|
||||
→ normalize/preprocess
|
||||
→ model inference
|
||||
→ convert pixel coords to geospatial coords
|
||||
→ merge/filter outputs
|
||||
→ save detections/segmentations
|
||||
→ expose as map layer
|
||||
```
|
||||
|
||||
## 9. CRS-regels
|
||||
|
||||
- Alle interne geometrieën worden opgeslagen in PostGIS met bekende SRID.
|
||||
- Voor metrische berekeningen wordt een geschikte projectie gebruikt.
|
||||
- API-output naar frontend mag in EPSG:4326 of WebMercator-compatible formaat.
|
||||
- Elke dataset zonder CRS krijgt status `needs_crs_review`.
|
||||
|
||||
## 10. Developmentstrategie
|
||||
|
||||
Bouwvolgorde:
|
||||
|
||||
1. backend foundation
|
||||
2. database schema
|
||||
3. project/area API
|
||||
4. dataset upload en metadata
|
||||
5. frontend workspace en kaart
|
||||
6. vector import
|
||||
7. raster import
|
||||
8. processing jobs
|
||||
9. detection lab
|
||||
10. QA/QC
|
||||
11. export
|
||||
|
||||
Reference in New Issue
Block a user