# ktyfujkjdfx/bountyteam-carbon-mrv architecture

> Architecture diagram of the GitHub repository ktyfujkjdfx/bountyteam-carbon-mrv, 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/ktyfujkjdfx/bountyteam-carbon-mrv
- Repository: https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv

## Overview

BountyTeam Carbon MRV is a satellite forest-carbon verification and credit-management product, with a frontend for monitoring plots and initiating actions, a backend API and durable worker, and chain operations. The intended flow runs from plot verification through remote-sensing evidence and backend policy decisions to credit operations; confirmed fire reversal can plan a chain freeze. The README cautions that this baseline is not the completed application. Edges reflect sampled calls or explicit source descriptions; unsampled subsystem wiring is omitted.

Main entry points: [`backend/app/worker.py`](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/worker.py) (Durable worker), [`backend/app/main.py`](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/main.py) (API routes), [`backend/app/ingest.py`](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/ingest.py) (Evidence import), [`frontend/src/App.tsx`](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/App.tsx) (Dashboard app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User dashboard"]
  node_app["Dashboard app<br/>[App.tsx]"]
  node_api["API client<br/>[client.ts]"]
  node_tracked["Tracked actions"]
  node_http["HTTP client adapter<br/>[httpAdapter.ts]"]
  node_fixture["Fixture adapter<br/>[fixtureAdapter.ts]"]
end

subgraph group_sensing["Evidence generation"]
  node_pipeline["RS pipeline<br/>[pipeline.py]"]
  node_preview["Evidence previews<br/>[preview.py]"]
  node_firms["Fire attribution<br/>[firms.py]"]
end

subgraph group_backend["API and decisions"]
  node_api_routes["API routes<br/>[main.py]"]
  node_operations["Action operations<br/>[operations.py]"]
  node_views["Read views<br/>[views.py]"]
  node_ingest["Evidence import<br/>[ingest.py]"]
  node_policy["Decision policy<br/>[policy.py]"]
  node_database[("Application database<br/>[db.py]")]
  node_worker["Durable worker<br/>[worker.py]"]
end

subgraph group_chain["Chain operations"]
  node_chain_adapter["Chain adapter<br/>[web3_adapter.py]"]
end

node_user(("Demo user"))
node_browser[("Browser storage")]
node_chain[("Blockchain network")]

node_user -->|"uses dashboard"| node_app
node_app -->|"requests data"| node_api
node_app -->|"tracks actions"| node_tracked
node_tracked -->|"persists intents"| node_browser
node_api -->|"dispatches HTTP"| node_http
node_api -.->|"dispatches fixtures"| node_fixture
node_http -->|"sends requests"| node_api_routes
node_api_routes -->|"calls reads"| node_views
node_api_routes -->|"calls actions"| node_operations
node_operations -->|"persists work"| node_database
node_api_routes -.->|"imports evidence"| node_ingest
node_ingest -->|"validates by policy"| node_policy
node_ingest -->|"stores records"| node_database
node_pipeline -->|"fetches hotspots"| node_firms
node_pipeline -.->|"produces previews"| node_preview
node_worker -.->|"imports job evidence"| node_ingest
node_worker -->|"plans freezes"| node_operations
node_worker -->|"submits operations"| node_chain_adapter
node_chain_adapter -->|"sends transactions"| node_chain
node_worker -->|"reconciles state"| node_database

click node_app "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/client.ts"
click node_tracked "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/hooks/useTrackedAction.ts"
click node_pipeline "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/pipeline.py"
click node_preview "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/preview.py"
click node_firms "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/firms.py"
click node_http "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/httpAdapter.ts"
click node_fixture "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/fixtureAdapter.ts"
click node_api_routes "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/main.py"
click node_operations "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/operations.py"
click node_views "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/views.py"
click node_ingest "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/ingest.py"
click node_policy "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/policy.py"
click node_database "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/db.py"
click node_worker "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/worker.py"
click node_chain_adapter "https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/chain/web3_adapter.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_api,node_tracked,node_http,node_fixture,node_user toneBlue
class node_pipeline,node_preview,node_firms,node_browser,node_chain toneAmber
class node_api_routes,node_operations,node_views,node_ingest,node_policy,node_database,node_worker toneMint
class node_chain_adapter toneRose
```

## Components

### User dashboard

- [Dashboard app](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Tracked actions](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/hooks/useTrackedAction.ts): `frontend/src/hooks/useTrackedAction.ts`
- [HTTP client adapter](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/httpAdapter.ts): `frontend/src/api/httpAdapter.ts`
- [Fixture adapter](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/frontend/src/api/fixtureAdapter.ts): `frontend/src/api/fixtureAdapter.ts`

### Evidence generation

- [RS pipeline](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/pipeline.py): `rs/pipeline.py`
- [Evidence previews](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/preview.py): `rs/preview.py`
- [Fire attribution](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/rs/firms.py): `rs/firms.py`

### API and decisions

- [API routes](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/main.py): `backend/app/main.py`
- [Action operations](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/operations.py): `backend/app/operations.py`
- [Read views](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/views.py): `backend/app/views.py`
- [Evidence import](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/ingest.py): `backend/app/ingest.py`
- [Decision policy](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/policy.py): `backend/app/policy.py`
- [Application database](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/db.py): `backend/app/db.py`
- [Durable worker](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/worker.py): `backend/app/worker.py`

### Chain operations

- [Chain adapter](https://github.com/ktyfujkjdfx/bountyteam-carbon-mrv/blob/main/backend/app/chain/web3_adapter.py): `backend/app/chain/web3_adapter.py`

### Other components

- **Demo user**
- **Browser storage**
- **Blockchain network**

## Connections

- Demo user → Dashboard app: uses dashboard
- Dashboard app → API client: requests data
- Dashboard app → Tracked actions: tracks actions
- Tracked actions → Browser storage: persists intents
- API client → HTTP client adapter: dispatches HTTP
- API client → Fixture adapter: dispatches fixtures
- HTTP client adapter → API routes: sends requests
- API routes → Read views: calls reads
- API routes → Action operations: calls actions
- Action operations → Application database: persists work
- API routes → Evidence import: imports evidence
- Evidence import → Decision policy: validates by policy
- Evidence import → Application database: stores records
- RS pipeline → Fire attribution: fetches hotspots
- RS pipeline → Evidence previews: produces previews
- Durable worker → Evidence import: imports job evidence
- Durable worker → Action operations: plans freezes
- Durable worker → Chain adapter: submits operations
- Chain adapter → Blockchain network: sends transactions
- Durable worker → Application database: reconciles state