# user-account-hub/ki-portfolio-studie architecture

> Architecture diagram of the GitHub repository user-account-hub/ki-portfolio-studie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/user-account-hub/ki-portfolio-studie
- Repository: https://github.com/user-account-hub/ki-portfolio-studie
- Video tour (about a minute): https://gitdiagram.com/user-account-hub/ki-portfolio-studie/video

## Overview

This repository is a Claude-assisted paper-trading case study, not a live-money trading product. Its main workflow loads portfolio and market context, requests and validates a proposed decision, applies server-side sizing and risk checks before paper execution, then reconstructs performance and writes a report. The README also documents on-demand stress testing and monthly deep reflection. Connections follow the README and supplied source excerpts/index; unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/pipeline.py`](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/pipeline.py) (Run pipeline), [`src/execution.py`](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/execution.py) (Execution orchestrator), [`src/db.py`](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/db.py) (SQLite access), [`src/data_fetch.py`](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/data_fetch.py) (Market data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_pipeline["Run pipeline<br/>[pipeline.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_context["Decision context"]
  node_marketdata["Market data<br/>[data_fetch.py]"]
  node_fundamentals["Fundamentals<br/>[fundamentals.py]"]
  node_events["Event calendar<br/>[event_calendar.py]"]
  node_news["News feeds<br/>[news_feed.py]"]
  node_phase["Market phase<br/>[market_phase.py]"]
  node_prompt["Prompt builder<br/>[prompt_builder.py]"]
end

subgraph group_governance["Order governance"]
  node_parser["Decision parser<br/>[order_schema.py]"]
  node_sizing["Position sizing<br/>[position_sizing.py]"]
  node_guardrails["Risk guardrails<br/>[risk_guardrails.py]"]
end

subgraph group_trading["Portfolio trading"]
  node_execution["Execution orchestrator<br/>[execution.py]"]
  node_database[("Portfolio database<br/>[portfolio.db]")]
  node_dbaccess["SQLite access<br/>[db.py]"]
  node_boundaries["Boundary tracking"]
  node_correlation["Correlation review<br/>[correlation.py]"]
end

subgraph group_analysis["Review and reporting"]
  node_quality["Data quality<br/>[data_quality.py]"]
  node_reflection["Deep reflection"]
  node_stress["Historical stress test<br/>[stress_test.py]"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_reporting["Markdown reporting<br/>[reporting.py]"]
end

node_scheduler(("Scheduled run"))
node_claude{{"Claude API"}}
node_broker{{"Alpaca paper API"}}
node_yfinance{{"Market data provider"}}

node_scheduler -->|"triggers"| node_pipeline
node_pipeline -->|"loads settings"| node_config
node_pipeline -->|"fetches prices"| node_marketdata
node_marketdata -->|"retrieves data"| node_yfinance
node_pipeline -->|"loads context"| node_fundamentals
node_pipeline -->|"loads events"| node_events
node_pipeline -->|"loads news"| node_news
node_pipeline -->|"classifies market"| node_phase
node_pipeline -->|"builds prompt"| node_prompt
node_prompt -->|"provides context"| node_claude
node_pipeline -->|"requests decision"| node_claude
node_claude -->|"returns response"| node_pipeline
node_pipeline -->|"parses response"| node_parser
node_pipeline -->|"submits orders"| node_execution
node_execution -->|"scales orders"| node_sizing
node_execution -->|"checks orders"| node_guardrails
node_execution -->|"places paper orders"| node_broker
node_execution -->|"updates records"| node_dbaccess
node_dbaccess -->|"reads and writes"| node_database
node_execution -->|"checks correlation"| node_correlation
node_execution -->|"compares phases"| node_phase
node_pipeline -->|"tracks conditions"| node_boundaries
node_pipeline -->|"checks data"| node_quality
node_pipeline -->|"runs reflection"| node_reflection
node_pipeline -->|"runs stress test"| node_stress
node_pipeline -->|"calculates metrics"| node_metrics
node_metrics -->|"reads portfolio history"| node_dbaccess
node_pipeline -->|"writes report"| node_reporting

click node_pipeline "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/pipeline.py"
click node_config "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/config.py"
click node_marketdata "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/data_fetch.py"
click node_fundamentals "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/fundamentals.py"
click node_events "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/event_calendar.py"
click node_news "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/news_feed.py"
click node_phase "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/market_phase.py"
click node_prompt "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/prompt_builder.py"
click node_parser "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/order_schema.py"
click node_sizing "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/position_sizing.py"
click node_guardrails "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/risk_guardrails.py"
click node_execution "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/execution.py"
click node_database "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/db/portfolio.db"
click node_dbaccess "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/db.py"
click node_boundaries "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/boundary_conditions.py"
click node_correlation "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/correlation.py"
click node_quality "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/data_quality.py"
click node_reflection "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/deep_reflection_prompt.py"
click node_stress "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/stress_test.py"
click node_metrics "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/metrics.py"
click node_reporting "https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/reporting.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_config toneBlue
class node_marketdata,node_fundamentals,node_events,node_news,node_phase,node_prompt toneAmber
class node_parser,node_sizing,node_guardrails,node_claude,node_broker toneMint
class node_execution,node_database,node_dbaccess,node_boundaries,node_correlation toneRose
class node_quality,node_reflection,node_stress,node_metrics,node_reporting,node_scheduler,node_yfinance toneIndigo
```

## Components

### Run orchestration

- [Run pipeline](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/pipeline.py): `src/pipeline.py`
- [Configuration](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/config.py): `src/config.py`

### Decision context

- [Market data](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/data_fetch.py): `src/data_fetch.py`
- [Fundamentals](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/fundamentals.py): `src/fundamentals.py`
- [Event calendar](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/event_calendar.py): `src/event_calendar.py`
- [News feeds](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/news_feed.py): `src/news_feed.py`
- [Market phase](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/market_phase.py): `src/market_phase.py`
- [Prompt builder](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/prompt_builder.py): `src/prompt_builder.py`

### Order governance

- [Decision parser](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/order_schema.py): `src/order_schema.py`
- [Position sizing](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/position_sizing.py): `src/position_sizing.py`
- [Risk guardrails](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/risk_guardrails.py): `src/risk_guardrails.py`

### Portfolio trading

- [Execution orchestrator](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/execution.py): `src/execution.py`
- [Portfolio database](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/db/portfolio.db): `db/portfolio.db`
- [SQLite access](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/db.py): `src/db.py`
- [Boundary tracking](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/boundary_conditions.py): `src/boundary_conditions.py`
- [Correlation review](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/correlation.py): `src/correlation.py`

### Review and reporting

- [Data quality](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/data_quality.py): `src/data_quality.py`
- [Deep reflection](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/deep_reflection_prompt.py): `src/deep_reflection_prompt.py`
- [Historical stress test](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/stress_test.py): `src/stress_test.py`
- [Performance metrics](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/metrics.py): `src/metrics.py`
- [Markdown reporting](https://github.com/user-account-hub/ki-portfolio-studie/blob/master/src/reporting.py): `src/reporting.py`

### Other components

- **Scheduled run**
- **Claude API**
- **Alpaca paper API**
- **Market data provider**

## Connections

- Scheduled run → Run pipeline: triggers (evidence: `README.md`)
- Run pipeline → Configuration: loads settings (evidence: `src/pipeline.py`)
- Run pipeline → Market data: fetches prices (evidence: `src/pipeline.py`)
- Market data → Market data provider: retrieves data (evidence: `src/data_fetch.py`)
- Run pipeline → Fundamentals: loads context (evidence: `src/pipeline.py`)
- Run pipeline → Event calendar: loads events (evidence: `src/pipeline.py`)
- Run pipeline → News feeds: loads news (evidence: `src/pipeline.py`)
- Run pipeline → Market phase: classifies market (evidence: `src/pipeline.py`)
- Run pipeline → Prompt builder: builds prompt (evidence: `src/pipeline.py`)
- Prompt builder → Claude API: provides context (evidence: `README.md`)
- Run pipeline → Claude API: requests decision (evidence: `src/pipeline.py`)
- Claude API → Run pipeline: returns response (evidence: `README.md`)
- Run pipeline → Decision parser: parses response (evidence: `src/pipeline.py`)
- Run pipeline → Execution orchestrator: submits orders (evidence: `src/pipeline.py`)
- Execution orchestrator → Position sizing: scales orders (evidence: `src/execution.py`)
- Execution orchestrator → Risk guardrails: checks orders (evidence: `src/execution.py`)
- Execution orchestrator → Alpaca paper API: places paper orders (evidence: `README.md`)
- Execution orchestrator → SQLite access: updates records (evidence: `src/execution.py`)
- SQLite access → Portfolio database: reads and writes (evidence: `src/db.py`)
- Execution orchestrator → Correlation review: checks correlation (evidence: `src/execution.py`)
- Execution orchestrator → Market phase: compares phases (evidence: `src/execution.py`)
- Run pipeline → Boundary tracking: tracks conditions (evidence: `src/pipeline.py`)
- Run pipeline → Data quality: checks data (evidence: `src/pipeline.py`)
- Run pipeline → Deep reflection: runs reflection (evidence: `src/pipeline.py`)
- Run pipeline → Historical stress test: runs stress test (evidence: `README.md`)
- Run pipeline → Performance metrics: calculates metrics (evidence: `src/pipeline.py`)
- Performance metrics → SQLite access: reads portfolio history (evidence: `src/metrics.py`)
- Run pipeline → Markdown reporting: writes report (evidence: `src/pipeline.py`)
