# toijam-ghanashyam/pvt architecture

> Architecture diagram of the GitHub repository toijam-ghanashyam/pvt, 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/toijam-ghanashyam/pvt
- Repository: https://github.com/toijam-ghanashyam/pvt

## Overview

This repository is a cadastral land-record platform: users ingest geospatial sources, reconcile spatial data and detect conflicts, then inspect results for review and record harmonization. The frontend exposes ingestion, map, analytics, records, and conflict views. The tree also shows separate root-cause clustering, multi-agent boundary consensus, and evidence-ledger/commitment subsystems. Source excerpts confirm selected ingestion, conflict-engine, clustering, ledger, and consensus behavior; the README is empty, and unsampled integration wiring is omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/App.jsx) (Web app routing), [`api.py`](https://github.com/toijam-ghanashyam/pvt/blob/main/api.py) (Backend API), [`boundary_consensus/consensus/orchestrator.py`](https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/orchestrator.py) (Consensus orchestrator), [`spatial-evidence-ledger-backend/app.py`](https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/app.py) (Evidence ledger API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Web app routing<br/>[App.jsx]"]
  node_ingest_page["Ingestion page<br/>[IngestionPage.jsx]"]
  node_ingestion_hub["Upload and run controls<br/>[IngestionHub.jsx]"]
  node_map_page["Map view<br/>[MapPage.jsx]"]
  node_records_page["Land records<br/>[RecordsPage.jsx]"]
  node_conflicts_page["Conflict review<br/>[ConflictsPage.jsx]"]
  node_analytics_page["Analytics<br/>[AnalyticsPage.jsx]"]
end

subgraph group_spatial["Spatial processing"]
  node_api["Backend API<br/>[api.py]"]
  node_ingest["Spatial ingestion<br/>[ingest.py]"]
  node_spatial_db[("PostGIS records")]
  node_conflict_engine["Spatial conflict engine<br/>[conflict_engine.py]"]
end

subgraph group_resolution["Conflict resolution"]
  node_clustering_api["Clustering service API<br/>[app.py]"]
  node_clustering["Root-cause clustering"]
  node_cause["Cause analysis<br/>[cause_analyzer.py]"]
  node_consensus["Consensus orchestrator<br/>[orchestrator.py]"]
  node_auction["Proposal auction<br/>[auction.py]"]
  node_payoffs["Consensus payoffs<br/>[game_theory.py]"]
  node_agents["Stakeholder agents"]
end

subgraph group_trust["Evidence and audit"]
  node_ledger_api["Evidence ledger API<br/>[app.py]"]
  node_ledger["Parcel ledger files<br/>[ledger.py]"]
  node_commitment["Commitment logic<br/>[commitment.py]"]
  node_proof["ZK proof module<br/>[proof.py]"]
  node_audit[("Audit events")]
end

node_user(("Land-record user"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_ingest_page
node_app -->|"routes to"| node_map_page
node_app -->|"routes to"| node_records_page
node_app -->|"routes to"| node_conflicts_page
node_app -->|"routes to"| node_analytics_page
node_ingest_page -->|"fetches audit logs"| node_api
node_ingestion_hub -->|"uploads and dispatches"| node_api
node_api -->|"dispatches ingestion"| node_ingest
node_ingest -->|"writes plots"| node_spatial_db
node_api -->|"dispatches analysis"| node_conflict_engine
node_conflict_engine -->|"reads and writes"| node_spatial_db
node_clustering_api -->|"clusters conflicts"| node_clustering
node_clustering -->|"analyzes clusters"| node_cause
node_consensus -->|"requests proposals"| node_agents
node_consensus -->|"selects winner"| node_auction
node_consensus -->|"evaluates consensus"| node_payoffs
node_ledger_api -->|"reads and updates"| node_ledger
node_ledger_api -->|"generates commitment"| node_commitment
node_ledger_api -->|"records events"| node_audit

click node_app "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/App.jsx"
click node_ingest_page "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/IngestionPage.jsx"
click node_ingestion_hub "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/components/dashboard/IngestionHub.jsx"
click node_map_page "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/MapPage.jsx"
click node_records_page "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/RecordsPage.jsx"
click node_conflicts_page "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/ConflictsPage.jsx"
click node_analytics_page "https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/AnalyticsPage.jsx"
click node_api "https://github.com/toijam-ghanashyam/pvt/blob/main/api.py"
click node_ingest "https://github.com/toijam-ghanashyam/pvt/blob/main/ingest.py"
click node_conflict_engine "https://github.com/toijam-ghanashyam/pvt/blob/main/conflict_engine.py"
click node_clustering_api "https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/app.py"
click node_clustering "https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/clustering_engine.py"
click node_cause "https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/cause_analyzer.py"
click node_consensus "https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/orchestrator.py"
click node_auction "https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/auction.py"
click node_payoffs "https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/game_theory.py"
click node_agents "https://github.com/toijam-ghanashyam/pvt/tree/main/boundary_consensus/agents"
click node_ledger_api "https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/app.py"
click node_ledger "https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/ledger.py"
click node_commitment "https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/commitment.py"
click node_proof "https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-zk/proof.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_app,node_ingest_page,node_ingestion_hub,node_map_page,node_records_page,node_conflicts_page,node_analytics_page,node_user toneBlue
class node_api,node_ingest,node_spatial_db,node_conflict_engine toneAmber
class node_clustering_api,node_clustering,node_cause,node_consensus,node_auction,node_payoffs,node_agents toneMint
class node_ledger_api,node_ledger,node_commitment,node_proof,node_audit toneRose
```

## Components

### User interface

- [Web app routing](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Ingestion page](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/IngestionPage.jsx): `frontend/src/pages/dashboard/IngestionPage.jsx`
- [Upload and run controls](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/components/dashboard/IngestionHub.jsx): `frontend/src/components/dashboard/IngestionHub.jsx`
- [Map view](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/MapPage.jsx): `frontend/src/pages/dashboard/MapPage.jsx`
- [Land records](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/RecordsPage.jsx): `frontend/src/pages/dashboard/RecordsPage.jsx`
- [Conflict review](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/ConflictsPage.jsx): `frontend/src/pages/dashboard/ConflictsPage.jsx`
- [Analytics](https://github.com/toijam-ghanashyam/pvt/blob/main/frontend/src/pages/dashboard/AnalyticsPage.jsx): `frontend/src/pages/dashboard/AnalyticsPage.jsx`

### Spatial processing

- [Backend API](https://github.com/toijam-ghanashyam/pvt/blob/main/api.py): `api.py`
- [Spatial ingestion](https://github.com/toijam-ghanashyam/pvt/blob/main/ingest.py): `ingest.py`
- **PostGIS records**
- [Spatial conflict engine](https://github.com/toijam-ghanashyam/pvt/blob/main/conflict_engine.py): `conflict_engine.py`

### Conflict resolution

- [Clustering service API](https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/app.py): `conflict-clustering-service/app.py`
- [Root-cause clustering](https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/clustering_engine.py): `conflict-clustering-service/clustering_engine.py`
- [Cause analysis](https://github.com/toijam-ghanashyam/pvt/blob/main/conflict-clustering-service/cause_analyzer.py): `conflict-clustering-service/cause_analyzer.py`
- [Consensus orchestrator](https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/orchestrator.py): `boundary_consensus/consensus/orchestrator.py`
- [Proposal auction](https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/auction.py): `boundary_consensus/consensus/auction.py`
- [Consensus payoffs](https://github.com/toijam-ghanashyam/pvt/blob/main/boundary_consensus/consensus/game_theory.py): `boundary_consensus/consensus/game_theory.py`
- [Stakeholder agents](https://github.com/toijam-ghanashyam/pvt/tree/main/boundary_consensus/agents): `boundary_consensus/agents`

### Evidence and audit

- [Evidence ledger API](https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/app.py): `spatial-evidence-ledger-backend/app.py`
- [Parcel ledger files](https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/ledger.py): `spatial-evidence-ledger-backend/ledger.py`
- [Commitment logic](https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-backend/commitment.py): `spatial-evidence-ledger-backend/commitment.py`
- [ZK proof module](https://github.com/toijam-ghanashyam/pvt/blob/main/spatial-evidence-ledger-zk/proof.py): `spatial-evidence-ledger-zk/proof.py`
- **Audit events**

### Other components

- **Land-record user**

## Connections

- Land-record user → Web app routing: uses
- Web app routing → Ingestion page: routes to
- Web app routing → Map view: routes to
- Web app routing → Land records: routes to
- Web app routing → Conflict review: routes to
- Web app routing → Analytics: routes to
- Ingestion page → Backend API: fetches audit logs
- Upload and run controls → Backend API: uploads and dispatches
- Backend API → Spatial ingestion: dispatches ingestion
- Spatial ingestion → PostGIS records: writes plots
- Backend API → Spatial conflict engine: dispatches analysis
- Spatial conflict engine → PostGIS records: reads and writes
- Clustering service API → Root-cause clustering: clusters conflicts
- Root-cause clustering → Cause analysis: analyzes clusters
- Consensus orchestrator → Stakeholder agents: requests proposals
- Consensus orchestrator → Proposal auction: selects winner
- Consensus orchestrator → Consensus payoffs: evaluates consensus
- Evidence ledger API → Parcel ledger files: reads and updates
- Evidence ledger API → Commitment logic: generates commitment
- Evidence ledger API → Audit events: records events