# nirmal-aim/trinetra architecture

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

- Interactive diagram: https://gitdiagram.com/nirmal-aim/trinetra
- Repository: https://github.com/nirmal-aim/trinetra

## Overview

TRINETRA is a web platform for volumetric cadastral registration and vertical-property intelligence. Government users authenticate, ingest survey evidence, and follow a documented capture-to-registration workflow: preprocessing, floor extraction, candidate generation, optimization, mandatory validation, then ULPIN/passport issuance. Registered properties support GIS viewing, subsurface utilities, encroachment review, and temporal change detection; assistant queries and audit logs are separate capabilities. The backend pipeline excerpt shows candidate creation, QAOA, validation, and minting, but does not expose every API-to-service call. Other subsystem links follow the README’s documented responsibilities.

Main entry points: [`backend/app/main.py`](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/models/models.py`](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/models/models.py) (Property records), [`backend/app/services/pipeline_service.py`](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/pipeline_service.py) (Property pipeline), [`trinetra/src/App.tsx`](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/App.tsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_browser["Web app<br/>[App.tsx]"]
  node_ingestion_ui["Evidence intake<br/>[DataIngestion.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_city_data["City cadastre data"]
  node_verify_page["Public verification"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_datasets["Dataset intake<br/>[datasets.py]"]
end

subgraph group_workflow["Cadastral workflow"]
  node_preprocess["Preprocessing<br/>[preprocessing.py]"]
  node_extraction["Floor extraction<br/>[extraction.py]"]
  node_candidates["Volume candidates<br/>[candidates.py]"]
  node_pipeline["Property pipeline"]
  node_qubo["QUBO / QAOA<br/>[qaoa_service.py]"]
  node_validation["Cadastral validation"]
  node_ulpin["ULPIN / passport<br/>[ulpin_service.py]"]
end

subgraph group_records["Property records"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_records_db[("Property records<br/>[models.py]")]
end

subgraph group_operations["Spatial operations"]
  node_gis["GIS properties<br/>[gis.py]"]
  node_spatial["Spatial monitoring<br/>[spatial.py]"]
  node_assistant["GIS assistant<br/>[assistant.py]"]
  node_audit["Audit logs<br/>[audit.py]"]
end

node_user(("Government user"))

node_user -->|"uses"| node_browser
node_browser -->|"routes to"| node_ingestion_ui
node_browser -->|"routes to"| node_verify_page
node_ingestion_ui -->|"requests data"| node_api_client
node_api_client -->|"calls REST API"| node_backend
node_backend -->|"mounts router"| node_auth
node_backend -->|"mounts router"| node_datasets
node_backend -->|"mounts router"| node_preprocess
node_backend -->|"mounts router"| node_extraction
node_backend -->|"mounts router"| node_candidates
node_backend -->|"mounts router"| node_gis
node_backend -->|"mounts router"| node_spatial
node_backend -->|"mounts router"| node_assistant
node_backend -->|"mounts router"| node_audit
node_datasets -->|"ingests evidence"| node_pipeline
node_pipeline -->|"builds and runs"| node_qubo
node_pipeline -->|"validates candidate"| node_validation
node_pipeline -->|"issues identifier"| node_ulpin
node_pipeline -->|"creates records"| node_records_db
node_auth -->|"reads users"| node_records_db
node_db_session -->|"maps records"| node_records_db
node_gis -->|"reads property data"| node_records_db
node_spatial -->|"reads spatial records"| node_records_db
node_audit -->|"reads audit records"| node_records_db
node_city_data -->|"provides map data"| node_browser

click node_browser "https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/App.tsx"
click node_ingestion_ui "https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/screens/DataIngestion/DataIngestion.tsx"
click node_api_client "https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/services/api.ts"
click node_backend "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/main.py"
click node_auth "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/auth.py"
click node_datasets "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/datasets.py"
click node_preprocess "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/preprocessing.py"
click node_extraction "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/extraction.py"
click node_candidates "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/candidates.py"
click node_pipeline "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/pipeline_service.py"
click node_qubo "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/qaoa_service.py"
click node_validation "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/validation_service.py"
click node_ulpin "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/ulpin_service.py"
click node_gis "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/gis.py"
click node_spatial "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/spatial.py"
click node_assistant "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/assistant.py"
click node_audit "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/audit.py"
click node_db_session "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/database.py"
click node_records_db "https://github.com/nirmal-aim/trinetra/blob/main/backend/app/models/models.py"
click node_city_data "https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/data/realCityCadastreData.ts"
click node_verify_page "https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/pages/PublicVerifyPage.tsx"

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_browser,node_ingestion_ui,node_api_client,node_city_data,node_verify_page,node_user toneBlue
class node_backend,node_auth,node_datasets toneAmber
class node_preprocess,node_extraction,node_candidates,node_pipeline,node_qubo,node_validation,node_ulpin toneMint
class node_db_session,node_records_db toneRose
class node_gis,node_spatial,node_assistant,node_audit toneIndigo
```

## Components

### Web application

- [Web app](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/App.tsx): `trinetra/src/App.tsx`
- [Evidence intake](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/screens/DataIngestion/DataIngestion.tsx): `trinetra/src/screens/DataIngestion/DataIngestion.tsx`
- [API client](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/services/api.ts): `trinetra/src/services/api.ts`
- [City cadastre data](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/data/realCityCadastreData.ts): `trinetra/src/data/realCityCadastreData.ts`
- [Public verification](https://github.com/nirmal-aim/trinetra/blob/main/trinetra/src/pages/PublicVerifyPage.tsx): `trinetra/src/pages/PublicVerifyPage.tsx`

### Backend API

- [FastAPI app](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Dataset intake](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/datasets.py): `backend/app/api/datasets.py`

### Cadastral workflow

- [Preprocessing](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/preprocessing.py): `backend/app/api/preprocessing.py`
- [Floor extraction](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/extraction.py): `backend/app/api/extraction.py`
- [Volume candidates](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/candidates.py): `backend/app/api/candidates.py`
- [Property pipeline](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/pipeline_service.py): `backend/app/services/pipeline_service.py`
- [QUBO / QAOA](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/qaoa_service.py): `backend/app/services/qaoa_service.py`
- [Cadastral validation](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/validation_service.py): `backend/app/services/validation_service.py`
- [ULPIN / passport](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/services/ulpin_service.py): `backend/app/services/ulpin_service.py`

### Property records

- [Database sessions](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/database.py): `backend/app/database.py`
- [Property records](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/models/models.py): `backend/app/models/models.py`

### Spatial operations

- [GIS properties](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/gis.py): `backend/app/api/gis.py`
- [Spatial monitoring](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/spatial.py): `backend/app/api/spatial.py`
- [GIS assistant](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/assistant.py): `backend/app/api/assistant.py`
- [Audit logs](https://github.com/nirmal-aim/trinetra/blob/main/backend/app/api/audit.py): `backend/app/api/audit.py`

### Other components

- **Government user**

## Connections

- Government user → Web app: uses
- Web app → Evidence intake: routes to
- Web app → Public verification: routes to
- Evidence intake → API client: requests data
- API client → FastAPI app: calls REST API
- FastAPI app → Authentication: mounts router
- FastAPI app → Dataset intake: mounts router
- FastAPI app → Preprocessing: mounts router
- FastAPI app → Floor extraction: mounts router
- FastAPI app → Volume candidates: mounts router
- FastAPI app → GIS properties: mounts router
- FastAPI app → Spatial monitoring: mounts router
- FastAPI app → GIS assistant: mounts router
- FastAPI app → Audit logs: mounts router
- Dataset intake → Property pipeline: ingests evidence
- Property pipeline → QUBO / QAOA: builds and runs
- Property pipeline → Cadastral validation: validates candidate
- Property pipeline → ULPIN / passport: issues identifier
- Property pipeline → Property records: creates records
- Authentication → Property records: reads users
- Database sessions → Property records: maps records
- GIS properties → Property records: reads property data
- Spatial monitoring → Property records: reads spatial records
- Audit logs → Property records: reads audit records
- City cadastre data → Web app: provides map data