# jemsethio/lira-ai architecture

> Architecture diagram of the GitHub repository jemsethio/lira-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jemsethio/lira-ai
- Repository: https://github.com/jemsethio/lira-ai

## Overview

LIRA-AI is a landscape-regeneration decision platform: users move from project setup and evidence gathering through diagnosis and climate assessment to pathway, tradeoff, investment, community, advisory, and monitoring decisions. The README documents these capabilities and the backend’s specialist agents, scientific engines, data adapters, RAG, and MCP tools. Source excerpts confirm the application mounts routers and show selected engine, ingestion, and tool behavior; frontend-to-API wiring and many router internals were not sampled, so those links are left unverified.

Main entry points: [`backend/app/routers`](https://github.com/jemsethio/lira-ai/tree/main/backend/app/routers) (Domain API routes), [`frontend/src/app/[locale]/page.tsx`](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/page.tsx) (Decision pages), [`backend/app/mcp/server.py`](https://github.com/jemsethio/lira-ai/blob/main/backend/app/mcp/server.py) (Scientific MCP tools), [`backend/app/main.py`](https://github.com/jemsethio/lira-ai/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Decision workspace"]
  node_workspace["Decision pages<br/>[page.tsx]"]
  node_setup["Project setup<br/>[page.tsx]"]
  node_diagnosis_ui["Diagnosis view<br/>[page.tsx]"]
  node_climate_ui["Climate futures view<br/>[page.tsx]"]
  node_pathways_ui["Pathways view<br/>[page.tsx]"]
  node_investment_ui["Investment view<br/>[page.tsx]"]
  node_community_ui["Community view<br/>[page.tsx]"]
  node_monitoring_ui["Monitoring view<br/>[page.tsx]"]
end

subgraph group_api["Application API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_domain_routes["Domain API routes"]
  node_agent_api["Agent API<br/>[agents.py]"]
  node_mcp_http["MCP REST façade<br/>[mcp_router.py]"]
end

subgraph group_science["Landscape intelligence"]
  node_diagnosis["Diagnosis engines"]
  node_syndrome["Syndrome classification"]
  node_health["Landscape health index"]
  node_climate_agent["Climate futures agent"]
  node_pathway_engine["Pathway generation"]
  node_priority["Investment priority<br/>[priority_index.py]"]
  node_monitor_agent["Adaptive monitoring"]
  node_evidence_agent["Landscape evidence agent"]
end

subgraph group_evidence["Data and knowledge"]
  node_data_adapters["Geospatial data adapters"]
  node_cmip6["CMIP6 adapter<br/>[cmip6_adapter.py]"]
  node_gardian["CGIAR evidence adapter<br/>[gardian_adapter.py]"]
  node_rag[("Evidence ingestion and retrieval<br/>[ingestion.py]")]
end

subgraph group_platform["Tooling and services"]
  node_mcp["Scientific MCP tools<br/>[server.py]"]
  node_llm["Narrative generation<br/>[llm_service.py]"]
end

node_user(("Landscape decision-maker"))
node_external_data{{"Scientific data providers"}}

node_user -->|"uses"| node_workspace
node_workspace -.->|"starts project"| node_setup
node_setup -.->|"submits project"| node_api_app
node_workspace -.->|"reviews diagnosis"| node_diagnosis_ui
node_workspace -.->|"reviews climate"| node_climate_ui
node_workspace -.->|"reviews pathways"| node_pathways_ui
node_workspace -.->|"reviews investment"| node_investment_ui
node_workspace -.->|"reviews community"| node_community_ui
node_workspace -.->|"reviews monitoring"| node_monitoring_ui
node_api_app -->|"mounts routes"| node_domain_routes
node_api_app -->|"mounts routes"| node_agent_api
node_api_app -->|"mounts routes"| node_mcp_http
node_domain_routes -.->|"runs diagnosis"| node_diagnosis
node_domain_routes -.->|"requests climate assessment"| node_climate_agent
node_domain_routes -.->|"requests pathways"| node_pathway_engine
node_domain_routes -.->|"supports investment ranking"| node_priority
node_domain_routes -.->|"requests monitoring"| node_monitor_agent
node_domain_routes -.->|"requests evidence"| node_evidence_agent
node_diagnosis -.->|"classifies syndromes"| node_syndrome
node_diagnosis -.->|"scores health"| node_health
node_evidence_agent -->|"orchestrates sources"| node_data_adapters
node_external_data -->|"provides observations"| node_data_adapters
node_external_data -->|"provides projections"| node_cmip6
node_external_data -->|"provides publications"| node_gardian
node_domain_routes -.->|"serves knowledge search"| node_rag
node_domain_routes -->|"harvests evidence"| node_gardian
node_mcp_http -->|"dispatches tools"| node_mcp
node_mcp -->|"runs diagnostic tools"| node_diagnosis
node_mcp -->|"fetches climate data"| node_cmip6
node_mcp -->|"searches evidence"| node_gardian
node_mcp -.->|"retrieves documents"| node_rag
node_mcp -->|"generates packages"| node_pathway_engine
node_mcp -->|"generates narratives"| node_llm

click node_workspace "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/page.tsx"
click node_setup "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/setup/page.tsx"
click node_diagnosis_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/diagnosis/page.tsx"
click node_climate_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/climate/page.tsx"
click node_pathways_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/pathways/page.tsx"
click node_investment_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/investment/page.tsx"
click node_community_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/community/page.tsx"
click node_monitoring_ui "https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/monitoring/page.tsx"
click node_api_app "https://github.com/jemsethio/lira-ai/blob/main/backend/app/main.py"
click node_domain_routes "https://github.com/jemsethio/lira-ai/tree/main/backend/app/routers"
click node_agent_api "https://github.com/jemsethio/lira-ai/blob/main/backend/app/routers/agents.py"
click node_diagnosis "https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/indicator_engine.py"
click node_syndrome "https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/syndrome_classifier.py"
click node_health "https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/landscape_health_index.py"
click node_climate_agent "https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/climate_futures_agent.py"
click node_pathway_engine "https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/pathway_generator.py"
click node_priority "https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/priority_index.py"
click node_monitor_agent "https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/adaptive_monitoring_agent.py"
click node_evidence_agent "https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/landscape_evidence_agent.py"
click node_data_adapters "https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/planetary_computer.py"
click node_cmip6 "https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/cmip6_adapter.py"
click node_gardian "https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/gardian_adapter.py"
click node_rag "https://github.com/jemsethio/lira-ai/blob/main/backend/app/rag/ingestion.py"
click node_mcp "https://github.com/jemsethio/lira-ai/blob/main/backend/app/mcp/server.py"
click node_mcp_http "https://github.com/jemsethio/lira-ai/blob/main/backend/app/routers/mcp_router.py"
click node_llm "https://github.com/jemsethio/lira-ai/blob/main/backend/app/services/llm_service.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_workspace,node_setup,node_diagnosis_ui,node_climate_ui,node_pathways_ui,node_investment_ui,node_community_ui,node_monitoring_ui toneBlue
class node_api_app,node_domain_routes,node_agent_api,node_mcp_http toneAmber
class node_diagnosis,node_syndrome,node_health,node_climate_agent,node_pathway_engine,node_priority,node_monitor_agent,node_evidence_agent toneMint
class node_data_adapters,node_cmip6,node_gardian,node_rag toneRose
class node_mcp,node_llm,node_user,node_external_data toneIndigo
```

## Components

### Decision workspace

- [Decision pages](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/page.tsx): `frontend/src/app/[locale]/page.tsx`
- [Project setup](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/setup/page.tsx): `frontend/src/app/[locale]/setup/page.tsx`
- [Diagnosis view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/diagnosis/page.tsx): `frontend/src/app/[locale]/diagnosis/page.tsx`
- [Climate futures view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/climate/page.tsx): `frontend/src/app/[locale]/climate/page.tsx`
- [Pathways view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/pathways/page.tsx): `frontend/src/app/[locale]/pathways/page.tsx`
- [Investment view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/investment/page.tsx): `frontend/src/app/[locale]/investment/page.tsx`
- [Community view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/community/page.tsx): `frontend/src/app/[locale]/community/page.tsx`
- [Monitoring view](https://github.com/jemsethio/lira-ai/blob/main/frontend/src/app/%5Blocale%5D/monitoring/page.tsx): `frontend/src/app/[locale]/monitoring/page.tsx`

### Application API

- [FastAPI application](https://github.com/jemsethio/lira-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Domain API routes](https://github.com/jemsethio/lira-ai/tree/main/backend/app/routers): `backend/app/routers`
- [Agent API](https://github.com/jemsethio/lira-ai/blob/main/backend/app/routers/agents.py): `backend/app/routers/agents.py`
- [MCP REST façade](https://github.com/jemsethio/lira-ai/blob/main/backend/app/routers/mcp_router.py): `backend/app/routers/mcp_router.py`

### Landscape intelligence

- [Diagnosis engines](https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/indicator_engine.py): `backend/app/engines/indicator_engine.py`
- [Syndrome classification](https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/syndrome_classifier.py): `backend/app/engines/syndrome_classifier.py`
- [Landscape health index](https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/landscape_health_index.py): `backend/app/engines/landscape_health_index.py`
- [Climate futures agent](https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/climate_futures_agent.py): `backend/app/agents/climate_futures_agent.py`
- [Pathway generation](https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/pathway_generator.py): `backend/app/engines/pathway_generator.py`
- [Investment priority](https://github.com/jemsethio/lira-ai/blob/main/backend/app/engines/priority_index.py): `backend/app/engines/priority_index.py`
- [Adaptive monitoring](https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/adaptive_monitoring_agent.py): `backend/app/agents/adaptive_monitoring_agent.py`
- [Landscape evidence agent](https://github.com/jemsethio/lira-ai/blob/main/backend/app/agents/landscape_evidence_agent.py): `backend/app/agents/landscape_evidence_agent.py`

### Data and knowledge

- [Geospatial data adapters](https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/planetary_computer.py): `backend/app/data_adapters/planetary_computer.py`
- [CMIP6 adapter](https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/cmip6_adapter.py): `backend/app/data_adapters/cmip6_adapter.py`
- [CGIAR evidence adapter](https://github.com/jemsethio/lira-ai/blob/main/backend/app/data_adapters/gardian_adapter.py): `backend/app/data_adapters/gardian_adapter.py`
- [Evidence ingestion and retrieval](https://github.com/jemsethio/lira-ai/blob/main/backend/app/rag/ingestion.py): `backend/app/rag/ingestion.py`

### Tooling and services

- [Scientific MCP tools](https://github.com/jemsethio/lira-ai/blob/main/backend/app/mcp/server.py): `backend/app/mcp/server.py`
- [Narrative generation](https://github.com/jemsethio/lira-ai/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`

### Other components

- **Landscape decision-maker**
- **Scientific data providers**

## Connections

- Landscape decision-maker → Decision pages: uses
- Decision pages → Project setup: starts project
- Project setup → FastAPI application: submits project
- Decision pages → Diagnosis view: reviews diagnosis
- Decision pages → Climate futures view: reviews climate
- Decision pages → Pathways view: reviews pathways
- Decision pages → Investment view: reviews investment
- Decision pages → Community view: reviews community
- Decision pages → Monitoring view: reviews monitoring
- FastAPI application → Domain API routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Agent API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → MCP REST façade: mounts routes (evidence: `backend/app/main.py`)
- Domain API routes → Diagnosis engines: runs diagnosis
- Domain API routes → Climate futures agent: requests climate assessment
- Domain API routes → Pathway generation: requests pathways
- Domain API routes → Investment priority: supports investment ranking
- Domain API routes → Adaptive monitoring: requests monitoring
- Domain API routes → Landscape evidence agent: requests evidence
- Diagnosis engines → Syndrome classification: classifies syndromes
- Diagnosis engines → Landscape health index: scores health
- Landscape evidence agent → Geospatial data adapters: orchestrates sources
- Scientific data providers → Geospatial data adapters: provides observations
- Scientific data providers → CMIP6 adapter: provides projections
- Scientific data providers → CGIAR evidence adapter: provides publications
- Domain API routes → Evidence ingestion and retrieval: serves knowledge search (evidence: `backend/app/routers/rag.py`)
- Domain API routes → CGIAR evidence adapter: harvests evidence (evidence: `backend/app/routers/rag.py`)
- MCP REST façade → Scientific MCP tools: dispatches tools
- Scientific MCP tools → Diagnosis engines: runs diagnostic tools (evidence: `backend/app/mcp/server.py`)
- Scientific MCP tools → CMIP6 adapter: fetches climate data (evidence: `backend/app/mcp/server.py`)
- Scientific MCP tools → CGIAR evidence adapter: searches evidence (evidence: `backend/app/mcp/server.py`)
- Scientific MCP tools → Evidence ingestion and retrieval: retrieves documents (evidence: `backend/app/mcp/server.py`)
- Scientific MCP tools → Pathway generation: generates packages (evidence: `backend/app/mcp/server.py`)
- Scientific MCP tools → Narrative generation: generates narratives (evidence: `backend/app/mcp/server.py`)
