# seifabroud/decision-agents-gemini architecture

> Architecture diagram of the GitHub repository seifabroud/decision-agents-gemini, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seifabroud/decision-agents-gemini
- Repository: https://github.com/seifabroud/decision-agents-gemini

## Overview

Favorita is a sales decision-support platform: an offline pipeline prepares forecasts and analytical artifacts, which the Streamlit dashboard reads for exploration and reporting. Its agent workflow analyzes data, forecasts, recommends actions, checks cited numbers against replayable evidence, and produces reports; a separate assistant answers questions using tools and business-context retrieval. The README documents the pipeline and major dashboard capabilities; sampled source confirms key agent, tool, verification, and view relationships, but not every page’s wiring.

Main entry points: [`app/common.py`](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/common.py) (Shared dashboard data), [`agents/graph.py`](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/graph.py) (Analysis agent graph), [`agents/tools.py`](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/tools.py) (Evidence tools), [`agents/qa.py`](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/qa.py) (Question answering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and forecasting"]
  node_pipeline["Forecast pipeline<br/>[build.py]"]
  node_artifacts[("Analysis artifacts")]
end

subgraph group_dashboard["Decision dashboard"]
  node_streamlit["Dashboard entry<br/>[streamlit_app.py]"]
  node_common["Shared dashboard data<br/>[common.py]"]
  node_home["Overview<br/>[home.py]"]
  node_explorer["Store explorer<br/>[explorer.py]"]
  node_forecast_view["Forecast view<br/>[forecast.py]"]
  node_agent_view["Agent results<br/>[agents.py]"]
  node_assistant_view["Data assistant view<br/>[assistant.py]"]
  node_method_view["Method view<br/>[method.py]"]
end

subgraph group_agents["Agent workflows"]
  node_agent_graph["Analysis agent graph<br/>[graph.py]"]
  node_tools["Evidence tools<br/>[tools.py]"]
  node_verifier["Evidence verifier<br/>[verify.py]"]
  node_llm["LLM client<br/>[llm.py]"]
  node_qa["Question answering<br/>[qa.py]"]
end

subgraph group_knowledge["Knowledge and reporting"]
  node_rag["Business knowledge search<br/>[rag.py]"]
  node_kb["Business knowledge base"]
  node_report["Report generator<br/>[report.py]"]
end

node_analyst(("Decision maker"))
node_source_data["Favorita CSV"]
node_llm_service{{"Gemini or Claude"}}

node_analyst -->|"uses dashboard"| node_streamlit
node_source_data -->|"supplies sales"| node_pipeline
node_pipeline -->|"exports results"| node_artifacts
node_streamlit -->|"reads artifacts"| node_artifacts
node_home -->|"loads shared data"| node_common
node_explorer -->|"loads shared data"| node_common
node_forecast_view -->|"loads shared data"| node_common
node_agent_view -->|"sets up page"| node_common
node_assistant_view -->|"sets up page"| node_common
node_method_view -.->|"sets up page"| node_common
node_common -->|"reads Parquet and JSON"| node_artifacts
node_agent_view -->|"runs analysis"| node_agent_graph
node_agent_view -->|"builds reports"| node_report
node_agent_graph -->|"calls tools"| node_tools
node_agent_graph -->|"requests generation"| node_llm
node_agent_graph -.->|"retrieves context"| node_rag
node_agent_graph -->|"checks recommendations"| node_verifier
node_tools -->|"reads analysis data"| node_artifacts
node_qa -->|"invokes selected tools"| node_tools
node_qa -->|"requests answers"| node_llm
node_qa -->|"retrieves context"| node_rag
node_qa -->|"checks answer numbers"| node_verifier
node_verifier -->|"replays evidence"| node_tools
node_rag -->|"searches Markdown"| node_kb
node_report -->|"reads analysis data"| node_tools
node_llm -->|"calls provider"| node_llm_service

click node_pipeline "https://github.com/seifabroud/decision-agents-gemini/blob/main/pipeline/build.py"
click node_artifacts "https://github.com/seifabroud/decision-agents-gemini/tree/main/artifacts"
click node_streamlit "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/streamlit_app.py"
click node_common "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/common.py"
click node_home "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/home.py"
click node_explorer "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/explorer.py"
click node_forecast_view "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/forecast.py"
click node_agent_view "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/agents.py"
click node_assistant_view "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/assistant.py"
click node_method_view "https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/method.py"
click node_agent_graph "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/graph.py"
click node_tools "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/tools.py"
click node_verifier "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/verify.py"
click node_llm "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/llm.py"
click node_qa "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/qa.py"
click node_rag "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/rag.py"
click node_kb "https://github.com/seifabroud/decision-agents-gemini/tree/main/kb"
click node_report "https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/report.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_pipeline,node_artifacts toneBlue
class node_streamlit,node_common,node_home,node_explorer,node_forecast_view,node_agent_view,node_assistant_view,node_method_view toneAmber
class node_agent_graph,node_tools,node_verifier,node_llm,node_qa toneMint
class node_rag,node_kb,node_report toneRose
class node_analyst,node_source_data,node_llm_service toneIndigo
```

## Components

### Data and forecasting

- [Forecast pipeline](https://github.com/seifabroud/decision-agents-gemini/blob/main/pipeline/build.py): `pipeline/build.py`
- [Analysis artifacts](https://github.com/seifabroud/decision-agents-gemini/tree/main/artifacts): `artifacts`

### Decision dashboard

- [Dashboard entry](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Shared dashboard data](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/common.py): `app/common.py`
- [Overview](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/home.py): `app/views/home.py`
- [Store explorer](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/explorer.py): `app/views/explorer.py`
- [Forecast view](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/forecast.py): `app/views/forecast.py`
- [Agent results](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/agents.py): `app/views/agents.py`
- [Data assistant view](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/assistant.py): `app/views/assistant.py`
- [Method view](https://github.com/seifabroud/decision-agents-gemini/blob/main/app/views/method.py): `app/views/method.py`

### Agent workflows

- [Analysis agent graph](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/graph.py): `agents/graph.py`
- [Evidence tools](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/tools.py): `agents/tools.py`
- [Evidence verifier](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/verify.py): `agents/verify.py`
- [LLM client](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/llm.py): `agents/llm.py`
- [Question answering](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/qa.py): `agents/qa.py`

### Knowledge and reporting

- [Business knowledge search](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/rag.py): `agents/rag.py`
- [Business knowledge base](https://github.com/seifabroud/decision-agents-gemini/tree/main/kb): `kb`
- [Report generator](https://github.com/seifabroud/decision-agents-gemini/blob/main/agents/report.py): `agents/report.py`

### Other components

- **Decision maker**
- **Favorita CSV**
- **Gemini or Claude**

## Connections

- Decision maker → Dashboard entry: uses dashboard (evidence: `README.md`)
- Favorita CSV → Forecast pipeline: supplies sales (evidence: `README.md`)
- Forecast pipeline → Analysis artifacts: exports results (evidence: `README.md`)
- Dashboard entry → Analysis artifacts: reads artifacts (evidence: `README.md`)
- Overview → Shared dashboard data: loads shared data (evidence: `app/views/home.py`)
- Store explorer → Shared dashboard data: loads shared data (evidence: `app/views/explorer.py`)
- Forecast view → Shared dashboard data: loads shared data (evidence: `app/views/forecast.py`)
- Agent results → Shared dashboard data: sets up page (evidence: `app/views/agents.py`)
- Data assistant view → Shared dashboard data: sets up page (evidence: `app/views/assistant.py`)
- Method view → Shared dashboard data: sets up page (evidence: `app/views/method.py`)
- Shared dashboard data → Analysis artifacts: reads Parquet and JSON (evidence: `app/common.py`)
- Agent results → Analysis agent graph: runs analysis (evidence: `app/views/agents.py`)
- Agent results → Report generator: builds reports (evidence: `app/views/agents.py`)
- Analysis agent graph → Evidence tools: calls tools (evidence: `agents/graph.py`)
- Analysis agent graph → LLM client: requests generation (evidence: `agents/graph.py`)
- Analysis agent graph → Business knowledge search: retrieves context (evidence: `agents/graph.py`)
- Analysis agent graph → Evidence verifier: checks recommendations (evidence: `agents/graph.py`)
- Evidence tools → Analysis artifacts: reads analysis data (evidence: `agents/tools.py`)
- Question answering → Evidence tools: invokes selected tools (evidence: `agents/qa.py`)
- Question answering → LLM client: requests answers (evidence: `agents/qa.py`)
- Question answering → Business knowledge search: retrieves context (evidence: `agents/qa.py`)
- Question answering → Evidence verifier: checks answer numbers (evidence: `agents/qa.py`)
- Evidence verifier → Evidence tools: replays evidence (evidence: `agents/verify.py`)
- Business knowledge search → Business knowledge base: searches Markdown (evidence: `agents/rag.py`)
- Report generator → Evidence tools: reads analysis data (evidence: `agents/report.py`)
- LLM client → Gemini or Claude: calls provider (evidence: `README.md`)
