# jameslederman/alpha-daemon architecture

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

- Interactive diagram: https://gitdiagram.com/jameslederman/alpha-daemon
- Repository: https://github.com/jameslederman/alpha-daemon

## Overview

AlphaDaemon is point-in-time market research infrastructure. A run is created with a symbol and an as-of cutoff, then a Temporal workflow gathers evidence, plans research, retrieves and ranks SEC evidence, produces findings, and synthesizes a recommendation. A separate fundamental-analysis workflow prepares a filing corpus, lets a bounded analyst query SEC filings, news, and price history, and persists its result. The README also describes forecast assumptions and deterministic valuation as longer-term goals; those stages are not represented as implemented components. Some subsystem paths and wiring are based on README descriptions because their source was not sampled.

Main entry points: [`src/alpha-daemon/activities.py`](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/activities.py) (Research Activities), [`src/alpha-daemon/tools.py`](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/tools.py) (Domain Tools), [`src/alpha-daemon/storage.py`](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/storage.py) (Corpus Storage), [`src/alpha-daemon/workflows.py`](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/workflows.py) (Research Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run Entry"]
  node_runner["Run Launcher<br/>[run_workflow.py]"]
  node_api["Research API<br/>[api.py]"]
end

subgraph group_orchestration["Durable Orchestration"]
  node_worker["Worker<br/>[worker.py]"]
  node_research_flow["Research Workflow<br/>[workflows.py]"]
  node_fundamental_flow["Fundamental Workflow<br/>[workflows.py]"]
  node_activities["Research Activities<br/>[activities.py]"]
end

subgraph group_research["Research Capabilities"]
  node_analyst["Fundamental Analyst"]
  node_research_tools["Domain Tools<br/>[tools.py]"]
  node_market_provider["Market Data Provider<br/>[market_data.py]"]
  node_llm["LLM Client<br/>[llm.py]"]
  node_models["Research Models<br/>[models.py]"]
end

subgraph group_evidence["Evidence Infrastructure"]
  node_edgar["SEC Filing Access<br/>[edgar.py]"]
  node_retrieval["Chunking and Retrieval<br/>[retrieval.py]"]
  node_storage["Corpus Storage<br/>[storage.py]"]
end

node_user(("Research User"))
node_temporal["Temporal Service"]
node_massive["Massive API"]
node_sec["SEC EDGAR"]
node_postgres[("PostgreSQL Corpus")]
node_bedrock["Amazon Bedrock"]

node_user -->|"starts run"| node_runner
node_runner -->|"starts workflow"| node_temporal
node_api -->|"submits run"| node_temporal
node_worker -->|"registers tasks"| node_temporal
node_temporal -->|"dispatches"| node_research_flow
node_temporal -->|"dispatches"| node_fundamental_flow
node_research_flow -->|"executes activities"| node_activities
node_research_flow -->|"saves run"| node_activities
node_fundamental_flow -->|"prepares corpus"| node_activities
node_fundamental_flow -->|"invokes analysis"| node_analyst
node_analyst -->|"calls tools"| node_activities
node_activities -->|"uses capabilities"| node_research_tools
node_activities -->|"generates text"| node_llm
node_llm -->|"invokes model"| node_bedrock
node_research_tools -->|"fetches market data"| node_market_provider
node_market_provider -.->|"requests bars and news"| node_massive
node_research_tools -->|"fetches filings"| node_edgar
node_edgar -->|"requests SEC data"| node_sec
node_edgar -->|"reads and caches filings"| node_storage
node_research_tools -->|"chunks and ranks"| node_retrieval
node_activities -->|"retrieves evidence"| node_retrieval
node_research_tools -->|"reads and writes corpus"| node_storage
node_activities -->|"loads evidence"| node_storage
node_storage -->|"persists corpus and runs"| node_postgres
node_retrieval -->|"embeds evidence"| node_bedrock

click node_runner "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/run_workflow.py"
click node_api "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/api.py"
click node_worker "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/worker.py"
click node_research_flow "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/workflows.py"
click node_fundamental_flow "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/workflows.py"
click node_activities "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/activities.py"
click node_analyst "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/fundamental_analyst.py"
click node_research_tools "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/tools.py"
click node_market_provider "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/market_data.py"
click node_edgar "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/edgar.py"
click node_retrieval "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/retrieval.py"
click node_storage "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/storage.py"
click node_llm "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/llm.py"
click node_models "https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/models.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_runner,node_api,node_user toneBlue
class node_worker,node_research_flow,node_fundamental_flow,node_activities,node_postgres toneAmber
class node_analyst,node_research_tools,node_market_provider,node_llm,node_models,node_massive toneMint
class node_edgar,node_retrieval,node_storage toneRose
class node_temporal,node_sec,node_bedrock toneIndigo
```

## Components

### Run Entry

- [Run Launcher](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/run_workflow.py): `src/alpha-daemon/run_workflow.py`
- [Research API](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/api.py): `src/alpha-daemon/api.py`

### Durable Orchestration

- [Worker](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/worker.py): `src/alpha-daemon/worker.py`
- [Research Workflow](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/workflows.py): `src/alpha-daemon/workflows.py`
- [Fundamental Workflow](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/workflows.py): `src/alpha-daemon/workflows.py`
- [Research Activities](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/activities.py): `src/alpha-daemon/activities.py`

### Research Capabilities

- [Fundamental Analyst](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/fundamental_analyst.py): `src/alpha-daemon/fundamental_analyst.py`
- [Domain Tools](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/tools.py): `src/alpha-daemon/tools.py`
- [Market Data Provider](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/market_data.py): `src/alpha-daemon/market_data.py`
- [LLM Client](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/llm.py): `src/alpha-daemon/llm.py`
- [Research Models](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/models.py): `src/alpha-daemon/models.py`

### Evidence Infrastructure

- [SEC Filing Access](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/edgar.py): `src/alpha-daemon/edgar.py`
- [Chunking and Retrieval](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/retrieval.py): `src/alpha-daemon/retrieval.py`
- [Corpus Storage](https://github.com/jameslederman/alpha-daemon/blob/main/src/alpha-daemon/storage.py): `src/alpha-daemon/storage.py`

### Other components

- **Research User**
- **Temporal Service**
- **Massive API**
- **SEC EDGAR**
- **PostgreSQL Corpus**
- **Amazon Bedrock**

## Connections

- Research User → Run Launcher: starts run
- Run Launcher → Temporal Service: starts workflow
- Research API → Temporal Service: submits run
- Worker → Temporal Service: registers tasks
- Temporal Service → Research Workflow: dispatches
- Temporal Service → Fundamental Workflow: dispatches
- Research Workflow → Research Activities: executes activities
- Research Workflow → Research Activities: saves run
- Fundamental Workflow → Research Activities: prepares corpus
- Fundamental Workflow → Fundamental Analyst: invokes analysis
- Fundamental Analyst → Research Activities: calls tools
- Research Activities → Domain Tools: uses capabilities
- Research Activities → LLM Client: generates text
- LLM Client → Amazon Bedrock: invokes model
- Domain Tools → Market Data Provider: fetches market data
- Market Data Provider → Massive API: requests bars and news
- Domain Tools → SEC Filing Access: fetches filings
- SEC Filing Access → SEC EDGAR: requests SEC data
- SEC Filing Access → Corpus Storage: reads and caches filings
- Domain Tools → Chunking and Retrieval: chunks and ranks
- Research Activities → Chunking and Retrieval: retrieves evidence
- Domain Tools → Corpus Storage: reads and writes corpus
- Research Activities → Corpus Storage: loads evidence
- Corpus Storage → PostgreSQL Corpus: persists corpus and runs
- Chunking and Retrieval → Amazon Bedrock: embeds evidence