# magnusinst84-sudo/regenera-ledger architecture

> Architecture diagram of the GitHub repository magnusinst84-sudo/regenera-ledger, 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/magnusinst84-sudo/regenera-ledger
- Repository: https://github.com/magnusinst84-sudo/regenera-ledger

## Overview

Regenera Ledger is an ESG intelligence and regenerative-farmer offset marketplace. A company signs in, submits ESG material for forensic analysis, can add shipping-manifest data for Scope 3 review, calculates an emissions gap, then finds farmer projects to offset it; farmers can also submit data for AI estimation. The README documents these capabilities, while sampled source confirms the application entry points, authentication, Gemini client and manifest parsing. Detailed route-to-service wiring is not sampled, so those links reflect documented flows rather than inspected calls.

Main entry points: [`backend/routes/analysis.py`](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/analysis.py) (Analysis endpoints), [`frontend/src/App.jsx`](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/App.jsx) (Application routes), [`backend/main.py`](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/main.py) (FastAPI application), [`backend/db.py`](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/db.py) (Firestore access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["Application routes<br/>[App.jsx]"]
  node_company_dashboard["Company dashboard"]
  node_esg_page["ESG analysis<br/>[ESGAnalysis.jsx]"]
  node_scope_page["Scope 3 view<br/>[Scope3Viz.jsx]"]
  node_gap_page["Carbon gap<br/>[CarbonGap.jsx]"]
  node_matching_page["Project matching<br/>[Matching.jsx]"]
  node_farmer_page["Farmer estimation"]
  node_auth_context["Session state<br/>[AuthContext.jsx]"]
end

subgraph group_identity["Identity and API"]
  node_auth_routes["Auth endpoints<br/>[auth.py]"]
  node_auth_middleware["JWT access control<br/>[auth.py]"]
  node_api["FastAPI application<br/>[main.py]"]
  node_audit_routes["Audit endpoints<br/>[audit.py]"]
  node_audit_logger["Audit logging<br/>[audit_logger.py]"]
  node_db[("Firestore access<br/>[db.py]")]
end

subgraph group_carbon["Carbon intelligence"]
  node_analysis_routes["Analysis endpoints<br/>[analysis.py]"]
  node_pdf_parser["PDF extraction<br/>[pdf_extractor.py]"]
  node_manifest_parser["Manifest parsing<br/>[manifest_parser.py]"]
  node_scope_processor["Scope 3 processing"]
  node_carbon_calculator["Gap calculation"]
  node_gemini["Gemini inference<br/>[gemini_client.py]"]
end

subgraph group_marketplace["Farmer marketplace"]
  node_matching_routes["Matching endpoints<br/>[matching.py]"]
  node_farmer_matcher["Farmer matching<br/>[farmer_matcher.py]"]
  node_farmer_routes["Farmer endpoints<br/>[farmer.py]"]
end

node_company(("Company user"))
node_farmer(("Farmer user"))
node_gemini_service{{"Google Gemini"}}

node_company -->|"uses"| node_app
node_farmer -->|"uses"| node_app
node_app -->|"routes to"| node_company_dashboard
node_app -->|"routes to"| node_esg_page
node_app -->|"routes to"| node_scope_page
node_app -->|"routes to"| node_gap_page
node_app -->|"routes to"| node_matching_page
node_app -->|"routes to"| node_farmer_page
node_company -->|"signs in"| node_auth_context
node_farmer -->|"signs in"| node_auth_context
node_auth_context -->|"requests auth"| node_auth_routes
node_auth_routes -->|"issues tokens"| node_auth_middleware
node_auth_routes -->|"reads and writes"| node_db
node_api -->|"mounts"| node_auth_routes
node_api -->|"mounts"| node_analysis_routes
node_api -->|"mounts"| node_matching_routes
node_api -->|"mounts"| node_farmer_routes
node_api -->|"mounts"| node_audit_routes
node_esg_page -->|"submits report"| node_analysis_routes
node_analysis_routes -->|"extracts text"| node_pdf_parser
node_analysis_routes -->|"requests analysis"| node_gemini
node_gemini -->|"calls model"| node_gemini_service
node_analysis_routes -->|"stores results"| node_db
node_analysis_routes -->|"records action"| node_audit_logger
node_scope_page -->|"submits manifest"| node_analysis_routes
node_analysis_routes -->|"parses manifest"| node_manifest_parser
node_manifest_parser -->|"extracts PDF text"| node_pdf_parser
node_analysis_routes -->|"processes supply chain"| node_scope_processor
node_scope_page -->|"views emissions gap"| node_gap_page
node_analysis_routes -->|"calculates gap"| node_carbon_calculator
node_gap_page -->|"requests projects"| node_matching_routes
node_matching_routes -->|"finds farmers"| node_farmer_matcher
node_matching_routes -->|"reads and writes"| node_db
node_matching_page -->|"requests matches"| node_matching_routes
node_farmer_page -->|"submits farm data"| node_farmer_routes
node_farmer_routes -->|"requests estimation"| node_gemini
node_farmer_routes -->|"stores profile and estimate"| node_db
node_audit_routes -->|"reads audit records"| node_db
node_audit_logger -->|"writes audit records"| node_db

click node_app "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/App.jsx"
click node_company_dashboard "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/CompanyDashboard.jsx"
click node_esg_page "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/ESGAnalysis.jsx"
click node_scope_page "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/Scope3Viz.jsx"
click node_gap_page "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/CarbonGap.jsx"
click node_matching_page "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/Matching.jsx"
click node_farmer_page "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/FarmerEstimation.jsx"
click node_auth_context "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/context/AuthContext.jsx"
click node_auth_routes "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/auth.py"
click node_auth_middleware "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/middleware/auth.py"
click node_api "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/main.py"
click node_analysis_routes "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/analysis.py"
click node_pdf_parser "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/parsers/pdf_extractor.py"
click node_manifest_parser "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/parsers/manifest_parser.py"
click node_scope_processor "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/processors/scope3_processor.py"
click node_carbon_calculator "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/matching/carbon_calculator.py"
click node_gemini "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/ai/gemini_client.py"
click node_matching_routes "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/matching.py"
click node_farmer_matcher "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/matching/farmer_matcher.py"
click node_farmer_routes "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/farmer.py"
click node_audit_routes "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/audit.py"
click node_audit_logger "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/utils/audit_logger.py"
click node_db "https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/db.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_company_dashboard,node_esg_page,node_scope_page,node_gap_page,node_matching_page,node_farmer_page,node_auth_context,node_company,node_farmer toneBlue
class node_auth_routes,node_auth_middleware,node_api,node_audit_routes,node_audit_logger,node_db toneAmber
class node_analysis_routes,node_pdf_parser,node_manifest_parser,node_scope_processor,node_carbon_calculator,node_gemini toneMint
class node_matching_routes,node_farmer_matcher,node_farmer_routes toneRose
class node_gemini_service toneIndigo
```

## Components

### Web application

- [Application routes](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Company dashboard](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/CompanyDashboard.jsx): `frontend/src/pages/CompanyDashboard.jsx`
- [ESG analysis](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/ESGAnalysis.jsx): `frontend/src/pages/ESGAnalysis.jsx`
- [Scope 3 view](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/Scope3Viz.jsx): `frontend/src/pages/Scope3Viz.jsx`
- [Carbon gap](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/CarbonGap.jsx): `frontend/src/pages/CarbonGap.jsx`
- [Project matching](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/Matching.jsx): `frontend/src/pages/Matching.jsx`
- [Farmer estimation](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/pages/FarmerEstimation.jsx): `frontend/src/pages/FarmerEstimation.jsx`
- [Session state](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`

### Identity and API

- [Auth endpoints](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [JWT access control](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/middleware/auth.py): `backend/middleware/auth.py`
- [FastAPI application](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/main.py): `backend/main.py`
- [Audit endpoints](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/audit.py): `backend/routes/audit.py`
- [Audit logging](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/utils/audit_logger.py): `backend/utils/audit_logger.py`
- [Firestore access](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/db.py): `backend/db.py`

### Carbon intelligence

- [Analysis endpoints](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/analysis.py): `backend/routes/analysis.py`
- [PDF extraction](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/parsers/pdf_extractor.py): `backend/data/parsers/pdf_extractor.py`
- [Manifest parsing](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/parsers/manifest_parser.py): `backend/data/parsers/manifest_parser.py`
- [Scope 3 processing](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/processors/scope3_processor.py): `backend/data/processors/scope3_processor.py`
- [Gap calculation](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/matching/carbon_calculator.py): `backend/data/matching/carbon_calculator.py`
- [Gemini inference](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/ai/gemini_client.py): `backend/ai/gemini_client.py`

### Farmer marketplace

- [Matching endpoints](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/matching.py): `backend/routes/matching.py`
- [Farmer matching](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/data/matching/farmer_matcher.py): `backend/data/matching/farmer_matcher.py`
- [Farmer endpoints](https://github.com/magnusinst84-sudo/regenera-ledger/blob/main/backend/routes/farmer.py): `backend/routes/farmer.py`

### Other components

- **Company user**
- **Farmer user**
- **Google Gemini**

## Connections

- Company user → Application routes: uses
- Farmer user → Application routes: uses
- Application routes → Company dashboard: routes to
- Application routes → ESG analysis: routes to
- Application routes → Scope 3 view: routes to
- Application routes → Carbon gap: routes to
- Application routes → Project matching: routes to
- Application routes → Farmer estimation: routes to
- Company user → Session state: signs in
- Farmer user → Session state: signs in
- Session state → Auth endpoints: requests auth
- Auth endpoints → JWT access control: issues tokens
- Auth endpoints → Firestore access: reads and writes
- FastAPI application → Auth endpoints: mounts
- FastAPI application → Analysis endpoints: mounts
- FastAPI application → Matching endpoints: mounts
- FastAPI application → Farmer endpoints: mounts
- FastAPI application → Audit endpoints: mounts
- ESG analysis → Analysis endpoints: submits report
- Analysis endpoints → PDF extraction: extracts text
- Analysis endpoints → Gemini inference: requests analysis
- Gemini inference → Google Gemini: calls model
- Analysis endpoints → Firestore access: stores results
- Analysis endpoints → Audit logging: records action
- Scope 3 view → Analysis endpoints: submits manifest
- Analysis endpoints → Manifest parsing: parses manifest
- Manifest parsing → PDF extraction: extracts PDF text
- Analysis endpoints → Scope 3 processing: processes supply chain
- Scope 3 view → Carbon gap: views emissions gap
- Analysis endpoints → Gap calculation: calculates gap
- Carbon gap → Matching endpoints: requests projects
- Matching endpoints → Farmer matching: finds farmers
- Matching endpoints → Firestore access: reads and writes
- Project matching → Matching endpoints: requests matches
- Farmer estimation → Farmer endpoints: submits farm data
- Farmer endpoints → Gemini inference: requests estimation
- Farmer endpoints → Firestore access: stores profile and estimate
- Audit endpoints → Firestore access: reads audit records
- Audit logging → Firestore access: writes audit records