# dev-denish/platform architecture

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

- Interactive diagram: https://gitdiagram.com/dev-denish/platform
- Repository: https://github.com/dev-denish/platform

## Overview

#### Purpose and Runtime
dMRV is a Phase-1 land-use, forestry, and carbon-project monitoring platform that ingests satellite/geospatial data, runs analyses, renders map layers, and produces reports. It runs as a FastAPI modular monolith plus a React/Vite frontend served by nginx. Container orchestration is Docker Compose: `deploy/docker-compose.yml`.

#### Entry Points and Delivery
The API application factory owns lifecycle, middleware, error handling, and router registration in `backend/app/main.py`; the production ASGI entry point is `backend/app/asgi.py`. The SPA starts at `frontend/src/main.jsx` and composes routes/application state through `frontend/src/App.jsx`. Docker images are defined by `backend/Dockerfile` and `frontend/Dockerfile`.

#### Versioned API and Internal Boundaries
HTTP endpoints are grouped under a v1 router, including auth, projects, datasets, layers, analyses, jobs, reports, tile delivery, and WMS/external layers: `backend/app/api/v1/router.py`, `backend/app/api/v1/analyses.py`, `backend/app/api/v1/tiles.py`. Dependency injection and request authorization form the API boundary in `backend/app/api/deps.py`. The intended flow is API → service orchestration → repository persistence, with typed contracts and policy concepts in `backend/app/domain/dtos.py` and `backend/app/domain/authz.py`.

#### Persistence, Access Control, and Auditing
PostGIS is the material datastore, initialized and versioned through Alembic migrations: `backend/migrations/env.py`, `backend/migrations/versions/0001_initial.py`. Repositories isolate parameterized SQL for core aggregates and geospatial records, e.g. `backend/app/repositories/projects.py`, `backend/app/repositories/datasets.py`, and `backend/app/repositories/vector_layers.py`. Authentication, token handling, memberships, permission grants, and project-scoped access are separated into `backend/app/services/auth_service.py`, `backend/app/services/permission_service.py`, and `backend/app/services/project_access.py`.

#### Geospatial Ingestion and Layer Serving
Dataset ingestion is a bounded raster/vector pipeline that detects and processes COGs, rasters, vectors, and storage concerns: `backend/app/services/ingestion/service.py`, `backend/app/services/ingestion/raster.py`, `backend/app/services/ingestion/vector.py`. Ingested and external/WMS data become map-facing layers through `backend/app/services/tile_service.py`, `backend/app/services/tile_renderer.py`, and `backend/app/services/wms_service.py`. This is the main boundary between geospatial source formats/services and browser-consumable tiles/layer metadata.

#### Analysis and Background Execution
Analysis configuration/catalog definitions drive service-level Google Earth Engine (GEE) execution: `backend/app/domain/analysis_catalog.py`, `backend/app/services/gee_analysis_service.py`, `backend/app/services/gee_client.py`. Jobs decouple long-running GEE analyses and report generation from request handling: `backend/app/services/jobs_service.py`, `backend/app/workers/arq_worker.py`, `backend/app/workers/gee_analysis_jobs.py`. Redis/ARQ is implied by the queue-worker abstraction; the README specifies a threadpool-now/queue-later evolution boundary.

#### Frontend Map and Project Workspaces
The authenticated SPA organizes project lifecycle, upload, forest-definition, user, and WMS administration pages: `frontend/src/pages/ProjectDetailPage.jsx`, `frontend/src/pages/UploadPage.jsx`, `frontend/src/pages/ForestDefinitionPage.jsx`. Interactive map composition, draw/measure tools, layer controls, and analysis UI reside in `frontend/src/components/ProjectMap.jsx`, `frontend/src/components/LayersPanel.jsx`, and `frontend/src/components/AnalysisPanel.jsx`. Auth state and route enforcement are client-side boundaries at `frontend/src/context/AuthContext.jsx` and `frontend/src/routes/ProtectedRoute.jsx`.

#### Reporting and External Dependencies
Reports combine calculated content, charts, map images, and PDF rendering in `backend/app/services/report_service.py`, `backend/app/services/report_map_image.py`, and `backend/app/services/report_pdf.py`. Key external integrations are Google Earth Engine for satellite analysis, CDSE ingestion (`backend/app/services/cdse_ingestion.py`), external layer retrieval, and WMS servers. Operational security, rate limiting, metrics, and structured logging are centralized under `backend/app/core/security.py`, `backend/app/core/ratelimit.py`, and `backend/app/core/metrics.py`.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/dev-denish/platform/blob/main/backend/app/api/v1/router.py) (v1 endpoints), [`backend/app/services/tile_service.py`](https://github.com/dev-denish/platform/blob/main/backend/app/services/tile_service.py) (Layer and tile delivery), [`backend/app/workers/arq_worker.py`](https://github.com/dev-denish/platform/blob/main/backend/app/workers/arq_worker.py) (ARQ worker), [`backend/app/repositories/projects.py`](https://github.com/dev-denish/platform/blob/main/backend/app/repositories/projects.py) (Geospatial repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser SPA"]
  node_spa["React SPA<br/>Vite application<br/>[main.jsx]"]
  node_workspace["Project workspace<br/>pages and map UI"]
  node_auth_ui["Client auth guard<br/>auth state<br/>[AuthContext.jsx]"]
end

subgraph group_api["FastAPI monolith"]
  node_api_app["API application<br/>FastAPI factory<br/>[main.py]"]
  node_v1_api["v1 endpoints<br/>HTTP router<br/>[router.py]"]
  node_api_boundary["Request authorization<br/>dependencies<br/>[deps.py]"]
  node_domain["Domain contracts<br/>DTOs and policy<br/>[dtos.py]"]
  node_access["Identity and project access<br/>access services<br/>[auth_service.py]"]
end

subgraph group_geospatial["Geospatial and jobs"]
  node_ingestion["Dataset ingestion<br/>geospatial pipeline<br/>[service.py]"]
  node_layers["Layer and tile delivery<br/>map service<br/>[tile_service.py]"]
  node_analysis["GEE analysis<br/>analysis service"]
  node_jobs["Job orchestration<br/>background jobs<br/>[jobs_service.py]"]
  node_worker["ARQ worker<br/>worker runtime<br/>[arq_worker.py]"]
  node_reports["Report generation<br/>report service<br/>[report_service.py]"]
end

subgraph group_data["Persistence"]
  node_repositories["Geospatial repositories<br/>SQL repositories<br/>[projects.py]"]
  node_postgis[("PostGIS<br/>geospatial datastore<br/>[env.py]")]
end

subgraph group_external["External services"]
  node_gee{{"Google Earth Engine<br/>satellite analysis"}}
  node_sources{{"CDSE and WMS sources<br/>external geospatial data<br/>[cdse_ingestion.py]"}}
end

node_compose{{"Docker Compose<br/>orchestration<br/>[docker-compose.yml]"}}

node_compose -->|"runs"| node_spa
node_compose -->|"runs"| node_api_app
node_compose -->|"runs"| node_worker
node_spa -->|"uses"| node_auth_ui
node_spa -->|"renders"| node_workspace
node_auth_ui -->|"authenticated requests"| node_v1_api
node_workspace -->|"API requests"| node_v1_api
node_workspace -->|"map tiles and metadata"| node_layers
node_api_app -->|"registers"| node_v1_api
node_v1_api -->|"enforces"| node_api_boundary
node_api_boundary -->|"authorizes through"| node_access
node_v1_api -->|"uses contracts"| node_domain
node_v1_api -->|"submits datasets"| node_ingestion
node_v1_api -->|"serves layers"| node_layers
node_v1_api -->|"queues work"| node_jobs
node_v1_api -->|"requests reports"| node_reports
node_access -->|"reads and writes access data"| node_repositories
node_ingestion -->|"persists geospatial records"| node_repositories
node_layers -->|"reads layer metadata"| node_repositories
node_repositories -->|"parameterized SQL"| node_postgis
node_ingestion -->|"imports from"| node_sources
node_layers -->|"retrieves external layers"| node_sources
node_jobs -->|"dispatches"| node_worker
node_worker -->|"runs analyses"| node_analysis
node_worker -->|"generates reports"| node_reports
node_analysis -->|"executes"| node_gee
node_reports -->|"renders map images"| node_layers

click node_compose "https://github.com/dev-denish/platform/blob/main/deploy/docker-compose.yml"
click node_spa "https://github.com/dev-denish/platform/blob/main/frontend/src/main.jsx"
click node_workspace "https://github.com/dev-denish/platform/blob/main/frontend/src/pages/ProjectDetailPage.jsx"
click node_auth_ui "https://github.com/dev-denish/platform/blob/main/frontend/src/context/AuthContext.jsx"
click node_api_app "https://github.com/dev-denish/platform/blob/main/backend/app/main.py"
click node_v1_api "https://github.com/dev-denish/platform/blob/main/backend/app/api/v1/router.py"
click node_api_boundary "https://github.com/dev-denish/platform/blob/main/backend/app/api/deps.py"
click node_domain "https://github.com/dev-denish/platform/blob/main/backend/app/domain/dtos.py"
click node_access "https://github.com/dev-denish/platform/blob/main/backend/app/services/auth_service.py"
click node_ingestion "https://github.com/dev-denish/platform/blob/main/backend/app/services/ingestion/service.py"
click node_layers "https://github.com/dev-denish/platform/blob/main/backend/app/services/tile_service.py"
click node_analysis "https://github.com/dev-denish/platform/blob/main/backend/app/services/gee_analysis_service.py"
click node_jobs "https://github.com/dev-denish/platform/blob/main/backend/app/services/jobs_service.py"
click node_worker "https://github.com/dev-denish/platform/blob/main/backend/app/workers/arq_worker.py"
click node_reports "https://github.com/dev-denish/platform/blob/main/backend/app/services/report_service.py"
click node_repositories "https://github.com/dev-denish/platform/blob/main/backend/app/repositories/projects.py"
click node_postgis "https://github.com/dev-denish/platform/blob/main/backend/migrations/env.py"
click node_sources "https://github.com/dev-denish/platform/blob/main/backend/app/services/cdse_ingestion.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_spa,node_workspace,node_auth_ui toneBlue
class node_api_app,node_v1_api,node_api_boundary,node_domain,node_access toneAmber
class node_ingestion,node_layers,node_analysis,node_jobs,node_worker,node_reports toneMint
class node_repositories,node_postgis toneRose
class node_gee,node_sources toneIndigo
class node_compose toneNeutral
```

## Components

### Browser SPA

- [React SPA](https://github.com/dev-denish/platform/blob/main/frontend/src/main.jsx): Vite application · `frontend/src/main.jsx`
- [Project workspace](https://github.com/dev-denish/platform/blob/main/frontend/src/pages/ProjectDetailPage.jsx): pages and map UI · Project pages compose map, layers, uploads, and analysis controls. · `frontend/src/pages/ProjectDetailPage.jsx`
- [Client auth guard](https://github.com/dev-denish/platform/blob/main/frontend/src/context/AuthContext.jsx): auth state · `frontend/src/context/AuthContext.jsx`

### FastAPI monolith

- [API application](https://github.com/dev-denish/platform/blob/main/backend/app/main.py): FastAPI factory · Owns lifecycle, middleware, errors, and router registration. · `backend/app/main.py`
- [v1 endpoints](https://github.com/dev-denish/platform/blob/main/backend/app/api/v1/router.py): HTTP router · Exposes auth, projects, datasets, layers, analyses, jobs, reports, tiles, and WMS. · `backend/app/api/v1/router.py`
- [Request authorization](https://github.com/dev-denish/platform/blob/main/backend/app/api/deps.py): dependencies · Injects request dependencies and enforces authorization. · `backend/app/api/deps.py`
- [Domain contracts](https://github.com/dev-denish/platform/blob/main/backend/app/domain/dtos.py): DTOs and policy · `backend/app/domain/dtos.py`
- [Identity and project access](https://github.com/dev-denish/platform/blob/main/backend/app/services/auth_service.py): access services · Handles tokens, memberships, grants, and project-scoped authorization. · `backend/app/services/auth_service.py`

### Geospatial and jobs

- [Dataset ingestion](https://github.com/dev-denish/platform/blob/main/backend/app/services/ingestion/service.py): geospatial pipeline · Detects and processes raster, COG, vector, and storage inputs. · `backend/app/services/ingestion/service.py`
- [Layer and tile delivery](https://github.com/dev-denish/platform/blob/main/backend/app/services/tile_service.py): map service · Converts ingested and external data into layers and browser tiles. · `backend/app/services/tile_service.py`
- [GEE analysis](https://github.com/dev-denish/platform/blob/main/backend/app/services/gee_analysis_service.py): analysis service · Executes catalog-driven satellite analyses. · `backend/app/services/gee_analysis_service.py`
- [Job orchestration](https://github.com/dev-denish/platform/blob/main/backend/app/services/jobs_service.py): background jobs · Decouples long-running analyses and reports from HTTP requests. · `backend/app/services/jobs_service.py`
- [ARQ worker](https://github.com/dev-denish/platform/blob/main/backend/app/workers/arq_worker.py): worker runtime · `backend/app/workers/arq_worker.py`
- [Report generation](https://github.com/dev-denish/platform/blob/main/backend/app/services/report_service.py): report service · Combines calculated content, charts, map images, and PDFs. · `backend/app/services/report_service.py`

### Persistence

- [Geospatial repositories](https://github.com/dev-denish/platform/blob/main/backend/app/repositories/projects.py): SQL repositories · Isolate parameterized persistence for projects, datasets, and vector layers. · `backend/app/repositories/projects.py`
- [PostGIS](https://github.com/dev-denish/platform/blob/main/backend/migrations/env.py): geospatial datastore · `backend/migrations/env.py`

### External services

- **Google Earth Engine**: satellite analysis
- [CDSE and WMS sources](https://github.com/dev-denish/platform/blob/main/backend/app/services/cdse_ingestion.py): external geospatial data · Supplies satellite datasets and external map layers. · `backend/app/services/cdse_ingestion.py`

### Other components

- [Docker Compose](https://github.com/dev-denish/platform/blob/main/deploy/docker-compose.yml): orchestration · Deploys frontend, API, datastore, and worker runtime. · `deploy/docker-compose.yml`

## Connections

- Docker Compose → React SPA: runs
- Docker Compose → API application: runs
- Docker Compose → ARQ worker: runs
- React SPA → Client auth guard: uses
- React SPA → Project workspace: renders
- Client auth guard → v1 endpoints: authenticated requests
- Project workspace → v1 endpoints: API requests
- Project workspace → Layer and tile delivery: map tiles and metadata
- API application → v1 endpoints: registers
- v1 endpoints → Request authorization: enforces
- Request authorization → Identity and project access: authorizes through
- v1 endpoints → Domain contracts: uses contracts
- v1 endpoints → Dataset ingestion: submits datasets
- v1 endpoints → Layer and tile delivery: serves layers
- v1 endpoints → Job orchestration: queues work
- v1 endpoints → Report generation: requests reports
- Identity and project access → Geospatial repositories: reads and writes access data
- Dataset ingestion → Geospatial repositories: persists geospatial records
- Layer and tile delivery → Geospatial repositories: reads layer metadata
- Geospatial repositories → PostGIS: parameterized SQL
- Dataset ingestion → CDSE and WMS sources: imports from
- Layer and tile delivery → CDSE and WMS sources: retrieves external layers
- Job orchestration → ARQ worker: dispatches
- ARQ worker → GEE analysis: runs analyses
- ARQ worker → Report generation: generates reports
- GEE analysis → Google Earth Engine: executes
- Report generation → Layer and tile delivery: renders map images