# markusx5622/convergia architecture

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

- Interactive diagram: https://gitdiagram.com/markusx5622/convergia
- Repository: https://github.com/markusx5622/convergia
- Video tour (about a minute): https://gitdiagram.com/markusx5622/convergia/video

## Overview

Convergia is an industrial multi-stakeholder decision simulator. Users select or build a scenario, configure stakeholders and options, then run a deterministic, round-based debate whose scores, vetoes, conflicts, concessions, and consensus support an explainable result and executive report. The Scenario Studio, sensitivity lab, guided demo, and session history are distinct product branches. Optional server-side LLM enrichment rewrites audited narrative only; it does not determine outcomes. The graph follows README-documented capabilities; sampled source confirms session persistence and the optional enrichment request path, while unsampled route wiring is not inferred.

Main entry points: [`src/engine/simulation.ts`](https://github.com/markusx5622/convergia/blob/main/src/engine/simulation.ts) (Round simulation), [`src/app/debate/page.tsx`](https://github.com/markusx5622/convergia/blob/main/src/app/debate/page.tsx) (Debate view), [`src/lib/useBuilderStore.ts`](https://github.com/markusx5622/convergia/blob/main/src/lib/useBuilderStore.ts) (Builder workflow), [`src/app/studio/page.tsx`](https://github.com/markusx5622/convergia/blob/main/src/app/studio/page.tsx) (Scenario Studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_home["Product hub<br/>[page.tsx]"]
  node_scenario["Scenario explorer<br/>[page.tsx]"]
  node_stakeholders["Stakeholder profiles<br/>[page.tsx]"]
  node_debate["Debate view<br/>[page.tsx]"]
  node_result["Decision result<br/>[page.tsx]"]
  node_report["Executive report<br/>[page.tsx]"]
  node_demo["Guided demo<br/>[page.tsx]"]
end

subgraph group_modeling["Scenario modeling"]
  node_studio["Scenario Studio<br/>[page.tsx]"]
  node_builder["Builder workflow<br/>[useBuilderStore.ts]"]
  node_validation["Scenario validation"]
  node_conversion["Builder conversion<br/>[builder-convert.ts]"]
  node_scenario_data["Scenario catalog<br/>[index.ts]"]
  node_lab["Sensitivity lab<br/>[page.tsx]"]
end

subgraph group_engine["Decision engine"]
  node_simulation["Round simulation<br/>[simulation.ts]"]
  node_scoring["Scoring<br/>[scoring.ts]"]
  node_veto["Veto rules<br/>[veto.ts]"]
  node_conflict["Conflict analysis<br/>[conflict.ts]"]
  node_concession["Iterative concessions<br/>[concession.ts]"]
  node_consensus["Consensus status<br/>[consensus.ts]"]
  node_narrative["Deterministic explanations<br/>[narrative.ts]"]
  node_report_data["Report assembly<br/>[report.ts]"]
end

subgraph group_integrations["Persistence and AI"]
  node_history["Session history<br/>[page.tsx]"]
  node_session_store[("Local session store<br/>[storage-manager.ts]")]
  node_ai_hook["AI narrative request<br/>[useAINarrative.ts]"]
  node_enrich_route["Enrichment proxy<br/>[route.ts]"]
  node_enrichment["Narrative enrichment<br/>[enrichment.ts]"]
  node_llm_client["Chat completion client<br/>[client.ts]"]
end

node_user(("Decision maker"))
node_llm_provider{{"LLM provider"}}

node_user -->|"opens"| node_home
node_home -->|"selects scenario"| node_scenario
node_scenario -->|"continues setup"| node_stakeholders
node_stakeholders -->|"starts debate"| node_debate
node_debate -->|"runs rounds"| node_simulation
node_simulation -->|"calculates scores"| node_scoring
node_simulation -->|"checks red lines"| node_veto
node_simulation -->|"measures conflict"| node_conflict
node_simulation -->|"updates positions"| node_concession
node_simulation -->|"determines status"| node_consensus
node_simulation -->|"derives explanations"| node_narrative
node_debate -->|"presents outcome"| node_result
node_result -->|"opens report"| node_report
node_report -->|"renders report"| node_report_data
node_user -->|"builds scenario"| node_studio
node_studio -->|"edits draft"| node_builder
node_builder -->|"validates draft"| node_validation
node_builder -->|"converts draft"| node_conversion
node_conversion -->|"provides inputs"| node_simulation
node_studio -->|"saves completed draft"| node_session_store
node_user -->|"chooses preset"| node_scenario_data
node_scenario_data -->|"provides presets"| node_scenario
node_user -->|"varies weights"| node_lab
node_lab -->|"reruns simulation"| node_simulation
node_user -->|"starts guided demo"| node_demo
node_user -->|"reviews sessions"| node_history
node_history -->|"loads or deletes"| node_session_store
node_session_store -->|"restores draft"| node_builder
node_debate -.->|"requests optional prose"| node_ai_hook
node_ai_hook -.->|"posts sanitized input"| node_enrich_route
node_enrich_route -.->|"requests enrichment"| node_enrichment
node_enrichment -.->|"formats completion"| node_llm_client
node_llm_client -.->|"sends prompt"| node_llm_provider
node_ai_hook -.->|"supplies optional prose"| node_result

click node_home "https://github.com/markusx5622/convergia/blob/main/src/app/page.tsx"
click node_scenario "https://github.com/markusx5622/convergia/blob/main/src/app/scenario/page.tsx"
click node_stakeholders "https://github.com/markusx5622/convergia/blob/main/src/app/stakeholders/page.tsx"
click node_debate "https://github.com/markusx5622/convergia/blob/main/src/app/debate/page.tsx"
click node_result "https://github.com/markusx5622/convergia/blob/main/src/app/result/page.tsx"
click node_report "https://github.com/markusx5622/convergia/blob/main/src/app/report/page.tsx"
click node_studio "https://github.com/markusx5622/convergia/blob/main/src/app/studio/page.tsx"
click node_builder "https://github.com/markusx5622/convergia/blob/main/src/lib/useBuilderStore.ts"
click node_validation "https://github.com/markusx5622/convergia/blob/main/src/lib/builder-validation.ts"
click node_conversion "https://github.com/markusx5622/convergia/blob/main/src/lib/builder-convert.ts"
click node_scenario_data "https://github.com/markusx5622/convergia/blob/main/src/data/scenarios/index.ts"
click node_lab "https://github.com/markusx5622/convergia/blob/main/src/app/lab/page.tsx"
click node_demo "https://github.com/markusx5622/convergia/blob/main/src/app/demo/page.tsx"
click node_simulation "https://github.com/markusx5622/convergia/blob/main/src/engine/simulation.ts"
click node_scoring "https://github.com/markusx5622/convergia/blob/main/src/engine/scoring.ts"
click node_veto "https://github.com/markusx5622/convergia/blob/main/src/engine/veto.ts"
click node_conflict "https://github.com/markusx5622/convergia/blob/main/src/engine/conflict.ts"
click node_concession "https://github.com/markusx5622/convergia/blob/main/src/engine/concession.ts"
click node_consensus "https://github.com/markusx5622/convergia/blob/main/src/engine/consensus.ts"
click node_narrative "https://github.com/markusx5622/convergia/blob/main/src/engine/narrative.ts"
click node_report_data "https://github.com/markusx5622/convergia/blob/main/src/engine/report.ts"
click node_history "https://github.com/markusx5622/convergia/blob/main/src/app/history/page.tsx"
click node_session_store "https://github.com/markusx5622/convergia/blob/main/src/lib/storage-manager.ts"
click node_ai_hook "https://github.com/markusx5622/convergia/blob/main/src/lib/useAINarrative.ts"
click node_enrich_route "https://github.com/markusx5622/convergia/blob/main/src/app/api/llm/enrich/route.ts"
click node_enrichment "https://github.com/markusx5622/convergia/blob/main/src/services/llm/enrichment.ts"
click node_llm_client "https://github.com/markusx5622/convergia/blob/main/src/services/llm/client.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_home,node_scenario,node_stakeholders,node_debate,node_result,node_report,node_demo toneBlue
class node_studio,node_builder,node_validation,node_conversion,node_scenario_data,node_lab toneAmber
class node_simulation,node_scoring,node_veto,node_conflict,node_concession,node_consensus,node_narrative,node_report_data toneMint
class node_history,node_session_store,node_ai_hook,node_enrich_route,node_enrichment,node_llm_client toneRose
class node_user,node_llm_provider toneIndigo
```

## Components

### User experience

- [Product hub](https://github.com/markusx5622/convergia/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Scenario explorer](https://github.com/markusx5622/convergia/blob/main/src/app/scenario/page.tsx): `src/app/scenario/page.tsx`
- [Stakeholder profiles](https://github.com/markusx5622/convergia/blob/main/src/app/stakeholders/page.tsx): `src/app/stakeholders/page.tsx`
- [Debate view](https://github.com/markusx5622/convergia/blob/main/src/app/debate/page.tsx): `src/app/debate/page.tsx`
- [Decision result](https://github.com/markusx5622/convergia/blob/main/src/app/result/page.tsx): `src/app/result/page.tsx`
- [Executive report](https://github.com/markusx5622/convergia/blob/main/src/app/report/page.tsx): `src/app/report/page.tsx`
- [Guided demo](https://github.com/markusx5622/convergia/blob/main/src/app/demo/page.tsx): `src/app/demo/page.tsx`

### Scenario modeling

- [Scenario Studio](https://github.com/markusx5622/convergia/blob/main/src/app/studio/page.tsx): `src/app/studio/page.tsx`
- [Builder workflow](https://github.com/markusx5622/convergia/blob/main/src/lib/useBuilderStore.ts): `src/lib/useBuilderStore.ts`
- [Scenario validation](https://github.com/markusx5622/convergia/blob/main/src/lib/builder-validation.ts): `src/lib/builder-validation.ts`
- [Builder conversion](https://github.com/markusx5622/convergia/blob/main/src/lib/builder-convert.ts): `src/lib/builder-convert.ts`
- [Scenario catalog](https://github.com/markusx5622/convergia/blob/main/src/data/scenarios/index.ts): `src/data/scenarios/index.ts`
- [Sensitivity lab](https://github.com/markusx5622/convergia/blob/main/src/app/lab/page.tsx): `src/app/lab/page.tsx`

### Decision engine

- [Round simulation](https://github.com/markusx5622/convergia/blob/main/src/engine/simulation.ts): `src/engine/simulation.ts`
- [Scoring](https://github.com/markusx5622/convergia/blob/main/src/engine/scoring.ts): `src/engine/scoring.ts`
- [Veto rules](https://github.com/markusx5622/convergia/blob/main/src/engine/veto.ts): `src/engine/veto.ts`
- [Conflict analysis](https://github.com/markusx5622/convergia/blob/main/src/engine/conflict.ts): `src/engine/conflict.ts`
- [Iterative concessions](https://github.com/markusx5622/convergia/blob/main/src/engine/concession.ts): `src/engine/concession.ts`
- [Consensus status](https://github.com/markusx5622/convergia/blob/main/src/engine/consensus.ts): `src/engine/consensus.ts`
- [Deterministic explanations](https://github.com/markusx5622/convergia/blob/main/src/engine/narrative.ts): `src/engine/narrative.ts`
- [Report assembly](https://github.com/markusx5622/convergia/blob/main/src/engine/report.ts): `src/engine/report.ts`

### Persistence and AI

- [Session history](https://github.com/markusx5622/convergia/blob/main/src/app/history/page.tsx): `src/app/history/page.tsx`
- [Local session store](https://github.com/markusx5622/convergia/blob/main/src/lib/storage-manager.ts): `src/lib/storage-manager.ts`
- [AI narrative request](https://github.com/markusx5622/convergia/blob/main/src/lib/useAINarrative.ts): `src/lib/useAINarrative.ts`
- [Enrichment proxy](https://github.com/markusx5622/convergia/blob/main/src/app/api/llm/enrich/route.ts): `src/app/api/llm/enrich/route.ts`
- [Narrative enrichment](https://github.com/markusx5622/convergia/blob/main/src/services/llm/enrichment.ts): `src/services/llm/enrichment.ts`
- [Chat completion client](https://github.com/markusx5622/convergia/blob/main/src/services/llm/client.ts): `src/services/llm/client.ts`

### Other components

- **Decision maker**
- **LLM provider**

## Connections

- Decision maker → Product hub: opens
- Product hub → Scenario explorer: selects scenario
- Scenario explorer → Stakeholder profiles: continues setup
- Stakeholder profiles → Debate view: starts debate
- Debate view → Round simulation: runs rounds
- Round simulation → Scoring: calculates scores
- Round simulation → Veto rules: checks red lines
- Round simulation → Conflict analysis: measures conflict
- Round simulation → Iterative concessions: updates positions
- Round simulation → Consensus status: determines status
- Round simulation → Deterministic explanations: derives explanations
- Debate view → Decision result: presents outcome
- Decision result → Executive report: opens report
- Executive report → Report assembly: renders report
- Decision maker → Scenario Studio: builds scenario
- Scenario Studio → Builder workflow: edits draft
- Builder workflow → Scenario validation: validates draft
- Builder workflow → Builder conversion: converts draft
- Builder conversion → Round simulation: provides inputs
- Scenario Studio → Local session store: saves completed draft
- Decision maker → Scenario catalog: chooses preset
- Scenario catalog → Scenario explorer: provides presets
- Decision maker → Sensitivity lab: varies weights
- Sensitivity lab → Round simulation: reruns simulation
- Decision maker → Guided demo: starts guided demo
- Decision maker → Session history: reviews sessions
- Session history → Local session store: loads or deletes
- Local session store → Builder workflow: restores draft
- Debate view → AI narrative request: requests optional prose
- AI narrative request → Enrichment proxy: posts sanitized input
- Enrichment proxy → Narrative enrichment: requests enrichment
- Narrative enrichment → Chat completion client: formats completion
- Chat completion client → LLM provider: sends prompt
- AI narrative request → Decision result: supplies optional prose