# adivseth/aladeen-capital-research architecture

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

- Interactive diagram: https://gitdiagram.com/adivseth/aladeen-capital-research
- Repository: https://github.com/adivseth/aladeen-capital-research

## Overview

AlaDeen is a local AI research firm for Indian listed companies. A user starts research from the dashboard or CLI; the run manager launches the CIO-led process, which gathers a verified fact pack, briefs research desks, obtains deterministic valuation and audit results, conducts debate and risk review, then publishes a report and records the rating. The dashboard also exposes archives and call scoring. The README documents the major workflow and capabilities; some subsystem links rely on those descriptions because their implementations were not excerpted.

Main entry points: [`aladeen/firm/orchestrator.py`](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py) (CIO orchestrator), [`aladeen/server/app.py`](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/app.py) (Local dashboard), [`aladeen/quant/engine.py`](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/engine.py) (Quant engine), [`aladeen/server/runs.py`](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/runs.py) (Run manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_dashboard["Local dashboard<br/>[app.py]"]
  node_webui["Dashboard UI<br/>[app.js]"]
end

subgraph group_workflow["Research Workflow"]
  node_runmanager["Run manager<br/>[runs.py]"]
  node_cio["CIO orchestrator<br/>[orchestrator.py]"]
  node_desks["Research desks<br/>[staff.py]"]
  node_debate["Bull-bear debate<br/>[orchestrator.py]"]
  node_risk["Risk office<br/>[orchestrator.py]"]
  node_council["Independent council<br/>[orchestrator.py]"]
end

subgraph group_data["Research Data"]
  node_factpack["Fact pack<br/>[factpack.py]"]
  node_marketdata["Market data sources"]
  node_docfetch["Filing documents<br/>[documents.py]"]
end

subgraph group_analysis["Analysis and Review"]
  node_quant["Quant engine<br/>[engine.py]"]
  node_technicals["Technical analysis<br/>[technicals.py]"]
  node_statements["Statement reconciliation<br/>[statements.py]"]
  node_valuation["Valuation models<br/>[valuation.py]"]
  node_compliance["Compliance audit<br/>[audit.py]"]
  node_llm["Model providers<br/>[llm.py]"]
end

subgraph group_records["Publishing and Records"]
  node_report["Report renderer<br/>[render.py]"]
  node_archive[("Research archive<br/>[store.py]")]
  node_calllog[("Call log<br/>[store.py]")]
  node_scoring["Call scoring<br/>[scoring.py]"]
end

node_user(("Researcher"))

node_user -->|"starts research"| node_dashboard
node_dashboard -->|"serves interface"| node_webui
node_dashboard -->|"starts runs"| node_runmanager
node_runmanager -->|"launches"| node_cio
node_cio -->|"collects"| node_factpack
node_factpack -->|"fetches data"| node_marketdata
node_factpack -->|"loads documents"| node_docfetch
node_cio -->|"briefs and reviews"| node_desks
node_desks -->|"requests analysis"| node_llm
node_cio -->|"runs calculations"| node_quant
node_quant -->|"reconciles"| node_statements
node_quant -->|"computes indicators"| node_technicals
node_quant -->|"calculates value"| node_valuation
node_cio -->|"conducts debate"| node_debate
node_cio -->|"requests risk review"| node_risk
node_cio -->|"audits figures"| node_compliance
node_cio -->|"requests review"| node_council
node_cio -->|"publishes research"| node_report
node_report -->|"records rating"| node_calllog
node_runmanager -->|"updates runs"| node_archive
node_dashboard -->|"serves call log"| node_calllog
node_dashboard -->|"scores calls"| node_scoring
node_scoring -->|"fetches prices"| node_marketdata

click node_dashboard "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/app.py"
click node_webui "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/web/app.js"
click node_runmanager "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/runs.py"
click node_cio "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py"
click node_factpack "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/dataflows/factpack.py"
click node_marketdata "https://github.com/adivseth/aladeen-capital-research/tree/main/aladeen/dataflows"
click node_docfetch "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/dataflows/documents.py"
click node_quant "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/engine.py"
click node_technicals "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/technicals.py"
click node_statements "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/statements.py"
click node_valuation "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/valuation.py"
click node_desks "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/staff.py"
click node_debate "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py"
click node_risk "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py"
click node_compliance "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/audit.py"
click node_council "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py"
click node_llm "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/llm.py"
click node_report "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/report/render.py"
click node_archive "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/store.py"
click node_calllog "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/calllog/store.py"
click node_scoring "https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/calllog/scoring.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_dashboard,node_webui toneBlue
class node_runmanager,node_cio,node_desks,node_debate,node_risk,node_council toneAmber
class node_factpack,node_marketdata,node_docfetch toneMint
class node_quant,node_technicals,node_statements,node_valuation,node_compliance,node_llm toneRose
class node_report,node_archive,node_calllog,node_scoring,node_user toneIndigo
```

## Components

### User Interface

- [Local dashboard](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/app.py): `aladeen/server/app.py`
- [Dashboard UI](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/web/app.js): `aladeen/web/app.js`

### Research Workflow

- [Run manager](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/runs.py): `aladeen/server/runs.py`
- [CIO orchestrator](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py): `aladeen/firm/orchestrator.py`
- [Research desks](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/staff.py): `aladeen/firm/staff.py`
- [Bull-bear debate](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py): `aladeen/firm/orchestrator.py`
- [Risk office](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py): `aladeen/firm/orchestrator.py`
- [Independent council](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/firm/orchestrator.py): `aladeen/firm/orchestrator.py`

### Research Data

- [Fact pack](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/dataflows/factpack.py): `aladeen/dataflows/factpack.py`
- [Market data sources](https://github.com/adivseth/aladeen-capital-research/tree/main/aladeen/dataflows): `aladeen/dataflows`
- [Filing documents](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/dataflows/documents.py): `aladeen/dataflows/documents.py`

### Analysis and Review

- [Quant engine](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/engine.py): `aladeen/quant/engine.py`
- [Technical analysis](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/technicals.py): `aladeen/quant/technicals.py`
- [Statement reconciliation](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/statements.py): `aladeen/quant/statements.py`
- [Valuation models](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/valuation.py): `aladeen/quant/valuation.py`
- [Compliance audit](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/quant/audit.py): `aladeen/quant/audit.py`
- [Model providers](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/llm.py): `aladeen/llm.py`

### Publishing and Records

- [Report renderer](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/report/render.py): `aladeen/report/render.py`
- [Research archive](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/server/store.py): `aladeen/server/store.py`
- [Call log](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/calllog/store.py): `aladeen/calllog/store.py`
- [Call scoring](https://github.com/adivseth/aladeen-capital-research/blob/main/aladeen/calllog/scoring.py): `aladeen/calllog/scoring.py`

### Other components

- **Researcher**

## Connections

- Researcher → Local dashboard: starts research
- Local dashboard → Dashboard UI: serves interface (evidence: `aladeen/server/app.py`)
- Local dashboard → Run manager: starts runs (evidence: `aladeen/server/app.py`)
- Run manager → CIO orchestrator: launches (evidence: `aladeen/server/runs.py`)
- CIO orchestrator → Fact pack: collects (evidence: `aladeen/firm/orchestrator.py`)
- Fact pack → Market data sources: fetches data (evidence: `aladeen/dataflows/factpack.py`)
- Fact pack → Filing documents: loads documents (evidence: `aladeen/dataflows/factpack.py`)
- CIO orchestrator → Research desks: briefs and reviews (evidence: `aladeen/firm/orchestrator.py`)
- Research desks → Model providers: requests analysis (evidence: `aladeen/firm/staff.py`)
- CIO orchestrator → Quant engine: runs calculations (evidence: `aladeen/firm/orchestrator.py`)
- Quant engine → Statement reconciliation: reconciles (evidence: `aladeen/quant/engine.py`)
- Quant engine → Technical analysis: computes indicators (evidence: `aladeen/quant/engine.py`)
- Quant engine → Valuation models: calculates value (evidence: `aladeen/quant/engine.py`)
- CIO orchestrator → Bull-bear debate: conducts debate (evidence: `aladeen/firm/orchestrator.py`)
- CIO orchestrator → Risk office: requests risk review (evidence: `aladeen/firm/orchestrator.py`)
- CIO orchestrator → Compliance audit: audits figures (evidence: `aladeen/firm/orchestrator.py`)
- CIO orchestrator → Independent council: requests review (evidence: `aladeen/firm/orchestrator.py`)
- CIO orchestrator → Report renderer: publishes research (evidence: `aladeen/firm/orchestrator.py`)
- Report renderer → Call log: records rating (evidence: `aladeen/report/render.py`)
- Run manager → Research archive: updates runs (evidence: `aladeen/server/runs.py`)
- Local dashboard → Call log: serves call log (evidence: `aladeen/server/app.py`)
- Local dashboard → Call scoring: scores calls (evidence: `aladeen/server/app.py`)
- Call scoring → Market data sources: fetches prices (evidence: `aladeen/calllog/scoring.py`)
