# jaden-corda/civitrust architecture

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

- Interactive diagram: https://gitdiagram.com/jaden-corda/civitrust
- Repository: https://github.com/jaden-corda/civitrust

## Overview

CiviTrust is a web platform for country and regional intelligence, forecasting, market relevance, and AI-assisted analysis. Users enter through the application, choose an intelligence or exploration view, and request reports or forecasts; the server exposes supporting live, model, and AI capabilities. The map preserves the major product branches visible in the tree and source index. Several UI and server modules were not excerpted, so connections for those branches rely only on the shown imports or documented scope, not inferred internal call sequences.

Main entry points: [`server.ts`](https://github.com/jaden-corda/civitrust/blob/main/server.ts) (HTTP server), [`src/App.tsx`](https://github.com/jaden-corda/civitrust/blob/main/src/App.tsx) (CiviTrust app), [`src/server/civiaiHybridRouter.ts`](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiHybridRouter.ts) (Intent arbitration), [`src/ml/pipeline.ts`](https://github.com/jaden-corda/civitrust/blob/main/src/ml/pipeline.ts) (ML pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["CiviTrust app<br/>[App.tsx]"]
  node_landing["Landing experience"]
  node_explore["Explore insights"]
  node_report["Report generator"]
  node_picker["Entity picker"]
end

subgraph group_intelligence["Intelligence and outlooks"]
  node_live["Live situations<br/>[liveSituation.ts]"]
  node_outlook["CiviTrust outlook"]
  node_research["Model research<br/>[modelResearch.ts]"]
  node_resilience["Structural resilience"]
  node_production["Production forecasts<br/>[productionMl.ts]"]
end

subgraph group_markets["Market analysis"]
  node_market["Market relevance<br/>[marketRelevance.ts]"]
  node_marketstream["Market stream<br/>[marketStream.ts]"]
end

subgraph group_assistant["AI assistance"]
  node_assistant_api["CiviAI service<br/>[civiai.ts]"]
  node_hybrid["Intent arbitration"]
  node_request_facts["Request facts"]
  node_intent_router["Question routing<br/>[civiaiRouter.ts]"]
  node_semantic_router["Semantic routing"]
end

subgraph group_models["Forecasting models"]
  node_ml_pipeline["ML pipeline<br/>[pipeline.ts]"]
  node_ingestion["Data ingestion<br/>[dataIngestion.ts]"]
  node_features["Feature engineering"]
  node_ml_models["Forecast models<br/>[models.ts]"]
end

node_user(("Analyst or user"))
node_server["HTTP server<br/>[server.ts]"]

node_user -->|"uses"| node_app
node_app -->|"shows"| node_landing
node_app -->|"navigates to"| node_explore
node_app -->|"opens"| node_report
node_report -->|"uses"| node_picker
node_server -->|"registers routes"| node_live
node_server -->|"imports"| node_outlook
node_server -->|"imports"| node_research
node_server -->|"imports"| node_resilience
node_server -->|"loads models"| node_production
node_server -->|"imports"| node_market
node_server -->|"imports"| node_marketstream
node_server -->|"imports"| node_assistant_api
node_assistant_api -.->|"dispatches to"| node_hybrid
node_hybrid -->|"extracts facts"| node_request_facts
node_hybrid -->|"routes questions"| node_intent_router
node_hybrid -.->|"uses decisions"| node_semantic_router
node_intent_router -->|"loads forecasts"| node_production
node_ml_pipeline -->|"fetches series"| node_ingestion
node_ml_pipeline -->|"extracts features"| node_features
node_ml_pipeline -->|"trains models"| node_ml_models

click node_app "https://github.com/jaden-corda/civitrust/blob/main/src/App.tsx"
click node_landing "https://github.com/jaden-corda/civitrust/blob/main/src/components/CiviTrustLanding.tsx"
click node_explore "https://github.com/jaden-corda/civitrust/blob/main/src/components/ExploreInsights.tsx"
click node_report "https://github.com/jaden-corda/civitrust/blob/main/src/components/ReportGenerator.tsx"
click node_picker "https://github.com/jaden-corda/civitrust/blob/main/src/components/SearchableEntityPicker.tsx"
click node_live "https://github.com/jaden-corda/civitrust/blob/main/src/server/liveSituation.ts"
click node_outlook "https://github.com/jaden-corda/civitrust/blob/main/src/server/civitrustOutlook.ts"
click node_research "https://github.com/jaden-corda/civitrust/blob/main/src/server/modelResearch.ts"
click node_resilience "https://github.com/jaden-corda/civitrust/blob/main/src/server/structuralResilience.ts"
click node_production "https://github.com/jaden-corda/civitrust/blob/main/src/server/productionMl.ts"
click node_market "https://github.com/jaden-corda/civitrust/blob/main/src/server/marketRelevance.ts"
click node_marketstream "https://github.com/jaden-corda/civitrust/blob/main/src/server/marketStream.ts"
click node_assistant_api "https://github.com/jaden-corda/civitrust/blob/main/src/server/civiai.ts"
click node_hybrid "https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiHybridRouter.ts"
click node_request_facts "https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiRequestFacts.ts"
click node_intent_router "https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiRouter.ts"
click node_semantic_router "https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiSemanticRouter.ts"
click node_ml_pipeline "https://github.com/jaden-corda/civitrust/blob/main/src/ml/pipeline.ts"
click node_ingestion "https://github.com/jaden-corda/civitrust/blob/main/src/ml/dataIngestion.ts"
click node_features "https://github.com/jaden-corda/civitrust/blob/main/src/ml/featureEngineering.ts"
click node_ml_models "https://github.com/jaden-corda/civitrust/blob/main/src/ml/models.ts"
click node_server "https://github.com/jaden-corda/civitrust/blob/main/server.ts"

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_landing,node_explore,node_report,node_picker,node_user toneBlue
class node_live,node_outlook,node_research,node_resilience,node_production toneAmber
class node_market,node_marketstream,node_server toneMint
class node_assistant_api,node_hybrid,node_request_facts,node_intent_router,node_semantic_router toneRose
class node_ml_pipeline,node_ingestion,node_features,node_ml_models toneIndigo
```

## Components

### User experience

- [CiviTrust app](https://github.com/jaden-corda/civitrust/blob/main/src/App.tsx): `src/App.tsx`
- [Landing experience](https://github.com/jaden-corda/civitrust/blob/main/src/components/CiviTrustLanding.tsx): `src/components/CiviTrustLanding.tsx`
- [Explore insights](https://github.com/jaden-corda/civitrust/blob/main/src/components/ExploreInsights.tsx): `src/components/ExploreInsights.tsx`
- [Report generator](https://github.com/jaden-corda/civitrust/blob/main/src/components/ReportGenerator.tsx): `src/components/ReportGenerator.tsx`
- [Entity picker](https://github.com/jaden-corda/civitrust/blob/main/src/components/SearchableEntityPicker.tsx): `src/components/SearchableEntityPicker.tsx`

### Intelligence and outlooks

- [Live situations](https://github.com/jaden-corda/civitrust/blob/main/src/server/liveSituation.ts): `src/server/liveSituation.ts`
- [CiviTrust outlook](https://github.com/jaden-corda/civitrust/blob/main/src/server/civitrustOutlook.ts): `src/server/civitrustOutlook.ts`
- [Model research](https://github.com/jaden-corda/civitrust/blob/main/src/server/modelResearch.ts): `src/server/modelResearch.ts`
- [Structural resilience](https://github.com/jaden-corda/civitrust/blob/main/src/server/structuralResilience.ts): `src/server/structuralResilience.ts`
- [Production forecasts](https://github.com/jaden-corda/civitrust/blob/main/src/server/productionMl.ts): `src/server/productionMl.ts`

### Market analysis

- [Market relevance](https://github.com/jaden-corda/civitrust/blob/main/src/server/marketRelevance.ts): `src/server/marketRelevance.ts`
- [Market stream](https://github.com/jaden-corda/civitrust/blob/main/src/server/marketStream.ts): `src/server/marketStream.ts`

### AI assistance

- [CiviAI service](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiai.ts): `src/server/civiai.ts`
- [Intent arbitration](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiHybridRouter.ts): `src/server/civiaiHybridRouter.ts`
- [Request facts](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiRequestFacts.ts): `src/server/civiaiRequestFacts.ts`
- [Question routing](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiRouter.ts): `src/server/civiaiRouter.ts`
- [Semantic routing](https://github.com/jaden-corda/civitrust/blob/main/src/server/civiaiSemanticRouter.ts): `src/server/civiaiSemanticRouter.ts`

### Forecasting models

- [ML pipeline](https://github.com/jaden-corda/civitrust/blob/main/src/ml/pipeline.ts): `src/ml/pipeline.ts`
- [Data ingestion](https://github.com/jaden-corda/civitrust/blob/main/src/ml/dataIngestion.ts): `src/ml/dataIngestion.ts`
- [Feature engineering](https://github.com/jaden-corda/civitrust/blob/main/src/ml/featureEngineering.ts): `src/ml/featureEngineering.ts`
- [Forecast models](https://github.com/jaden-corda/civitrust/blob/main/src/ml/models.ts): `src/ml/models.ts`

### Other components

- **Analyst or user**
- [HTTP server](https://github.com/jaden-corda/civitrust/blob/main/server.ts): `server.ts`

## Connections

- Analyst or user → CiviTrust app: uses (evidence: `src/App.tsx`)
- CiviTrust app → Landing experience: shows (evidence: `src/App.tsx`)
- CiviTrust app → Explore insights: navigates to (evidence: `src/App.tsx`)
- CiviTrust app → Report generator: opens (evidence: `src/App.tsx`)
- Report generator → Entity picker: uses (evidence: `src/components/ReportGenerator.tsx`)
- HTTP server → Live situations: registers routes (evidence: `server.ts`)
- HTTP server → CiviTrust outlook: imports (evidence: `server.ts`)
- HTTP server → Model research: imports (evidence: `server.ts`)
- HTTP server → Structural resilience: imports (evidence: `server.ts`)
- HTTP server → Production forecasts: loads models (evidence: `server.ts`)
- HTTP server → Market relevance: imports (evidence: `server.ts`)
- HTTP server → Market stream: imports (evidence: `server.ts`)
- HTTP server → CiviAI service: imports (evidence: `server.ts`)
- CiviAI service → Intent arbitration: dispatches to
- Intent arbitration → Request facts: extracts facts (evidence: `src/server/civiaiHybridRouter.ts`)
- Intent arbitration → Question routing: routes questions (evidence: `src/server/civiaiHybridRouter.ts`)
- Intent arbitration → Semantic routing: uses decisions (evidence: `src/server/civiaiHybridRouter.ts`)
- Question routing → Production forecasts: loads forecasts (evidence: `src/server/civiaiRouter.ts`)
- ML pipeline → Data ingestion: fetches series (evidence: `src/ml/pipeline.ts`)
- ML pipeline → Feature engineering: extracts features (evidence: `src/ml/pipeline.ts`)
- ML pipeline → Forecast models: trains models (evidence: `src/ml/pipeline.ts`)
