# shobika-p/ai-agent-coordination-decision-engine architecture

> Architecture diagram of the GitHub repository shobika-p/ai-agent-coordination-decision-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shobika-p/ai-agent-coordination-decision-engine
- Repository: https://github.com/shobika-p/ai-agent-coordination-decision-engine

## Overview

#### Purpose and Entry Points
This repository is an AI-assisted business decision-support workspace. A React/Vite dashboard submits business questions to a Flask REST API, which runs a LangGraph multi-agent workflow, persists reports and conversations, and returns decision analysis.

- Backend/API entry point: `app.py`
- Frontend entry points: `business-decision-ui/src/main.jsx`, `business-decision-ui/src/App.jsx`
- Deployment command definition: `Procfile`

#### API and Application Boundary
`app.py` is the backend integration boundary for report generation, follow-ups, what-if calculations, report-library CRUD, export, monitoring, and decision reruns. It accepts frontend requests, invokes graph/agent services, and serializes results for the UI.

The frontend API client centralizes HTTP calls in `business-decision-ui/src/services/api.js`. Main interaction surfaces include the submission form, report viewer, workflow status view, scenario panel, and persisted-report UI:
- `business-decision-ui/src/components/BusinessForm.jsx`
- `business-decision-ui/src/components/ReportViewer.jsx`
- `business-decision-ui/src/components/WorkflowVisualizer.jsx`
- `business-decision-ui/src/components/WhatIfPanel.jsx`

#### Decision Workflow Orchestration
The primary control flow is a LangGraph StateGraph defined in `graph/decision_graph.py`:

`START → tool selection/execution → research → planning → decision → report compilation → END`

The graph passes structured state across stages and exposes node status/metrics to the API/UI. Coordination and report-level assembly are represented by:
- `agents/coordination_agent.py`
- `agents/business_decision_engine.py`
- `graph/decision_graph.py`

#### Specialized AI Agent Stages
Agents isolate distinct reasoning responsibilities while sharing graph state:
- Research and market/context analysis: `agents/research_agent.py`
- Strategy and execution planning: `agents/planning_agent.py`
- Final viability/recommendation evaluation: `agents/decision_agent.py`
- Contextual question-answering after a generated report: `agents/followup_agent.py`
- Suggested next questions: `agents/suggest_followups_agent.py`

Prompt contracts are separated from execution logic in `prompts/research_prompt.py`, `prompts/planning_prompt.py`, and `prompts/decision_prompt.py`.

#### Quantitative Analysis Layer
Before or alongside LLM reasoning, tool selection and deterministic calculations provide financial and market inputs to the decision state. This is the boundary for ROI, profit, break-even, and risk computations:
- `tools/tool_selector.py`
- `tools/tool_manager.py`
- `tools/roi_tool.py`
- `tools/break_even_tool.py`
- `tools/market_risk_tool.py`

The what-if API applies adjustable operating assumptions to recompute outcomes for the UI scenario controls.

#### AI Runtime and Resilience
All Gemini interactions are intended to route through a centralized client, rather than agents directly owning provider behavior:
- `utils/gemini_client.py`
- `utils/llm_helper.py`
- `config.py`

This layer manages Gemini model calls, normalized caching, quota/rate-limit handling, retries, telemetry, and a demo/cache fallback when API credentials or quota are unavailable. External AI dependency: Google Gemini via LangChain Google GenAI.

#### Persistence, Reporting, and Exports
SQLite-backed storage maintains reports, scores, risk metadata, and report-specific conversation history:
- `memory/report_db.py`
- `memory/shared_memory.py`
- `memory/decision_engine.db`

Report export is a separate output boundary; PDF generation uses ReportLab, while API export also supports JSON and Markdown:
- `utils/pdf_generator.py`

#### Material Runtime Stack
Backend runtime is Python 3.11+, Flask with CORS, LangGraph/LangChain, SQLite3, and ReportLab. Frontend runtime is React 19 with Vite and Axios. The system normally runs as two local processes: Flask on port 5000 and Vite on port 5173; the frontend communicates solely through the REST API.

Main entry points: [`app.py`](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/app.py) (REST API), [`agents/research_agent.py`](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/research_agent.py) (Research analysis), [`agents/planning_agent.py`](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/planning_agent.py) (Strategy planning), [`agents/decision_agent.py`](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/decision_agent.py) (Viability decision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Dashboard"]
  node_ui_app["Dashboard shell<br/>React application<br/>[App.jsx]"]
  node_ui_api["API client<br/>Axios client<br/>[api.js]"]
  node_ui_submission["Question submission<br/>React form<br/>[BusinessForm.jsx]"]
  node_ui_results["Report and scenarios<br/>React views<br/>[ReportViewer.jsx]"]
end

subgraph group_api["Flask Application"]
  node_api_app{{"REST API<br/>Flask entry point<br/>[app.py]"}}
  node_deployment["Process command<br/>deployment entry"]
end

subgraph group_workflow["Decision Workflow"]
  node_decision_graph{{"StateGraph orchestration<br/>LangGraph workflow<br/>[decision_graph.py]"}}
  node_coordination["Coordination and assembly<br/>agent service"]
  node_research["Research analysis<br/>agent stage<br/>[research_agent.py]"]
  node_planning["Strategy planning<br/>agent stage<br/>[planning_agent.py]"]
  node_decision["Viability decision<br/>agent stage<br/>[decision_agent.py]"]
  node_followups["Follow-up assistance<br/>agent services<br/>[followup_agent.py]"]
end

subgraph group_runtime["AI, Data &amp; Output"]
  node_tools["Quantitative tools<br/>calculation layer<br/>[tool_selector.py]"]
  node_gemini{{"Gemini runtime<br/>LLM client<br/>[gemini_client.py]"}}
  node_prompts["Prompt contracts<br/>prompt definitions<br/>[research_prompt.py]"]
  node_report_store[("Report storage<br/>SQLite persistence<br/>[report_db.py]")]
  node_exports["Report exports<br/>output service<br/>[pdf_generator.py]"]
end

node_ui_app -->|"hosts"| node_ui_submission
node_ui_app -->|"hosts"| node_ui_results
node_ui_submission -->|"submits questions"| node_ui_api
node_ui_results -->|"requests reports and scenarios"| node_ui_api
node_ui_api -->|"REST"| node_api_app
node_deployment -.->|"starts"| node_api_app
node_api_app -->|"runs generation and reruns"| node_decision_graph
node_api_app -->|"handles report follow-ups"| node_followups
node_api_app -->|"runs what-if calculations"| node_tools
node_api_app -->|"reads and writes library"| node_report_store
node_api_app -->|"exports reports"| node_exports
node_decision_graph -->|"selects and executes"| node_tools
node_decision_graph -->|"research stage"| node_research
node_research -->|"context and findings"| node_planning
node_planning -->|"execution plan"| node_decision
node_decision -->|"recommendation"| node_coordination
node_coordination -->|"persists report"| node_report_store
node_research -.->|"uses"| node_prompts
node_planning -.->|"uses"| node_prompts
node_decision -.->|"uses"| node_prompts
node_research -->|"LLM calls"| node_gemini
node_planning -->|"LLM calls"| node_gemini
node_decision -->|"LLM calls"| node_gemini
node_followups -->|"LLM calls"| node_gemini
node_followups -->|"uses report context"| node_report_store

click node_ui_app "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/App.jsx"
click node_ui_api "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/services/api.js"
click node_ui_submission "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/components/BusinessForm.jsx"
click node_ui_results "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/components/ReportViewer.jsx"
click node_api_app "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/app.py"
click node_deployment "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/Procfile"
click node_decision_graph "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/graph/decision_graph.py"
click node_coordination "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/coordination_agent.py"
click node_research "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/research_agent.py"
click node_planning "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/planning_agent.py"
click node_decision "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/decision_agent.py"
click node_followups "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/followup_agent.py"
click node_tools "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/tools/tool_selector.py"
click node_gemini "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/utils/gemini_client.py"
click node_prompts "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/prompts/research_prompt.py"
click node_report_store "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/memory/report_db.py"
click node_exports "https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/utils/pdf_generator.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_ui_app,node_ui_api,node_ui_submission,node_ui_results toneBlue
class node_api_app,node_deployment toneAmber
class node_decision_graph,node_coordination,node_research,node_planning,node_decision,node_followups toneMint
class node_tools,node_gemini,node_prompts,node_report_store,node_exports toneRose
```

## Components

### React Dashboard

- [Dashboard shell](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/App.jsx): React application · Hosts the decision-support workspace. · `business-decision-ui/src/App.jsx`
- [API client](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/services/api.js): Axios client · Centralizes all frontend REST calls. · `business-decision-ui/src/services/api.js`
- [Question submission](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/components/BusinessForm.jsx): React form · `business-decision-ui/src/components/BusinessForm.jsx`
- [Report and scenarios](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/business-decision-ui/src/components/ReportViewer.jsx): React views · Displays reports, workflow status, and what-if controls. · `business-decision-ui/src/components/ReportViewer.jsx`

### Flask Application

- [REST API](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/app.py): Flask entry point · Serves generation, follow-up, scenario, library, export, monitoring, and rerun endpoints. · `app.py`
- [Process command](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/Procfile): deployment entry · `Procfile`

### Decision Workflow

- [StateGraph orchestration](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/graph/decision_graph.py): LangGraph workflow · Runs tools, research, planning, decision, and report compilation over shared state. · `graph/decision_graph.py`
- [Coordination and assembly](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/coordination_agent.py): agent service · Coordinates graph work and assembles decision reports. · `agents/coordination_agent.py`
- [Research analysis](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/research_agent.py): agent stage · `agents/research_agent.py`
- [Strategy planning](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/planning_agent.py): agent stage · `agents/planning_agent.py`
- [Viability decision](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/decision_agent.py): agent stage · `agents/decision_agent.py`
- [Follow-up assistance](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/agents/followup_agent.py): agent services · Answers report-context questions and suggests next questions. · `agents/followup_agent.py`

### AI, Data & Output

- [Quantitative tools](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/tools/tool_selector.py): calculation layer · Selects and runs ROI, break-even, profit, and market-risk calculations. · `tools/tool_selector.py`
- [Gemini runtime](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/utils/gemini_client.py): LLM client · Centralizes provider calls, caching, retries, rate limits, telemetry, and fallback behavior. · `utils/gemini_client.py`
- [Prompt contracts](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/prompts/research_prompt.py): prompt definitions · `prompts/research_prompt.py`
- [Report storage](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/memory/report_db.py): SQLite persistence · Stores reports, scores, risk metadata, and report conversations. · `memory/report_db.py`
- [Report exports](https://github.com/shobika-p/ai-agent-coordination-decision-engine/blob/main/utils/pdf_generator.py): output service · Generates PDF and supports JSON and Markdown export. · `utils/pdf_generator.py`

## Connections

- Dashboard shell → Question submission: hosts
- Dashboard shell → Report and scenarios: hosts
- Question submission → API client: submits questions
- Report and scenarios → API client: requests reports and scenarios
- API client → REST API: REST
- Process command → REST API: starts
- REST API → StateGraph orchestration: runs generation and reruns
- REST API → Follow-up assistance: handles report follow-ups
- REST API → Quantitative tools: runs what-if calculations
- REST API → Report storage: reads and writes library
- REST API → Report exports: exports reports
- StateGraph orchestration → Quantitative tools: selects and executes
- StateGraph orchestration → Research analysis: research stage
- Research analysis → Strategy planning: context and findings
- Strategy planning → Viability decision: execution plan
- Viability decision → Coordination and assembly: recommendation
- Coordination and assembly → Report storage: persists report
- Research analysis → Prompt contracts: uses
- Strategy planning → Prompt contracts: uses
- Viability decision → Prompt contracts: uses
- Research analysis → Gemini runtime: LLM calls
- Strategy planning → Gemini runtime: LLM calls
- Viability decision → Gemini runtime: LLM calls
- Follow-up assistance → Gemini runtime: LLM calls
- Follow-up assistance → Report storage: uses report context