# oskarajaspinall-cell/paper-portfolio architecture

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

- Interactive diagram: https://gitdiagram.com/oskarajaspinall-cell/paper-portfolio
- Repository: https://github.com/oskarajaspinall-cell/paper-portfolio

## Overview

Paper Portfolio is a paper-trading stock research and portfolio system: it screens a global universe, researches candidates with Claude, applies deterministic portfolio rules, and tracks results against the S&P 500. Its weekly workflow is complemented by daily price, corporate-action, entry-watch, dip-radar, and funding-queue routines, plus dashboard and performance reporting. The README documents the product flow; sampled excerpts and the SOURCE INDEX support selected implementation links. Unsampled subsystem details are represented only where documented, so some edges are omitted.

Main entry points: [`scripts/weekly_run.py`](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/weekly_run.py) (Weekly workflow), [`scripts/portfolio.py`](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/portfolio.py) (Portfolio engine), [`scripts/screen.py`](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/screen.py) (Weekly screen), [`scripts/fact_sheet.py`](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/fact_sheet.py) (Fact sheets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research and screening"]
  node_universe["Stock universe<br/>[universe.py]"]
  node_screen["Weekly screen<br/>[screen.py]"]
  node_factsheet["Fact sheets<br/>[fact_sheet.py]"]
  node_valuation["Fair valuation<br/>[valuation.py]"]
end

subgraph group_decisions["Review and decisions"]
  node_claude["Claude agents<br/>[agents]"]
  node_weekly["Weekly workflow<br/>[weekly_run.py]"]
  node_weeklyscan["Holding review<br/>[weekly_scan.py]"]
  node_entryresearch["Entry research<br/>[entry_research.py]"]
end

subgraph group_portfolio["Portfolio operations"]
  node_portfolio["Portfolio engine<br/>[portfolio.py]"]
  node_risk["Position sizing<br/>[risk.py]"]
  node_regime["Macro regime<br/>[regime.py]"]
  node_funding["Funding queue<br/>[funding_queue.py]"]
  node_corpactions["Corporate actions"]
end

subgraph group_monitoring["Monitoring and reporting"]
  node_entrywatch["Entry watch<br/>[entry_watch.py]"]
  node_dipradar["Dip radar<br/>[dip_radar.py]"]
  node_decisionslog[("Decision log<br/>[decision_log.py]")]
  node_scorecard["Decision scorecard<br/>[scorecard.py]"]
  node_dashboard["Live dashboard<br/>[dashboard.py]"]
  node_attribution["Return attribution<br/>[attribution.py]"]
end

subgraph group_data["Market data"]
  node_datafetch["Fundamental data<br/>[fetch_data.py]"]
  node_prices["Portfolio prices<br/>[prices.py]"]
  node_market(("Market data services"))
end

node_owner(("Portfolio owner"))
node_benchmark(("S&amp;P 500 benchmark"))

node_owner -->|"runs review"| node_weekly
node_weekly -->|"fills orders"| node_portfolio
node_weekly -->|"checks holdings"| node_weeklyscan
node_weekly -->|"runs screen"| node_screen
node_screen -->|"ranks universe"| node_universe
node_screen -->|"reads fundamentals"| node_datafetch
node_screen -->|"deep dives"| node_factsheet
node_factsheet -->|"reads company data"| node_datafetch
node_factsheet -->|"requests fair value"| node_valuation
node_weekly -->|"starts agent sessions"| node_claude
node_claude -->|"researches candidates"| node_entryresearch
node_weekly -->|"records decisions"| node_decisionslog
node_weekly -->|"submits orders"| node_portfolio
node_portfolio -->|"sizes positions"| node_risk
node_portfolio -->|"gets quotes"| node_prices
node_portfolio -->|"uses cash reserve"| node_regime
node_portfolio -->|"queues blocked buys"| node_funding
node_portfolio -->|"applies adjustments"| node_corpactions
node_regime -->|"reads macro indicators"| node_market
node_prices -->|"fetches price history"| node_market
node_weekly -->|"checks entry hits"| node_entrywatch
node_weekly -->|"runs dip radar"| node_dipradar
node_entrywatch -->|"flags hit stocks"| node_entryresearch
node_dipradar -->|"flags dip signals"| node_entryresearch
node_weekly -->|"checks evaluations"| node_scorecard
node_weekly -->|"refreshes dashboard"| node_dashboard
node_weekly -->|"reports returns"| node_attribution
node_decisionslog -->|"scores against"| node_benchmark
node_owner -->|"views portfolio"| node_dashboard

click node_universe "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/universe.py"
click node_screen "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/screen.py"
click node_datafetch "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/fetch_data.py"
click node_factsheet "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/fact_sheet.py"
click node_valuation "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/valuation.py"
click node_claude "https://github.com/oskarajaspinall-cell/paper-portfolio/tree/main/.claude/agents"
click node_weekly "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/weekly_run.py"
click node_weeklyscan "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/weekly_scan.py"
click node_entryresearch "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/entry_research.py"
click node_portfolio "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/portfolio.py"
click node_risk "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/risk.py"
click node_regime "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/regime.py"
click node_funding "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/funding_queue.py"
click node_corpactions "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/corporate_actions.py"
click node_entrywatch "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/entry_watch.py"
click node_dipradar "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/dip_radar.py"
click node_decisionslog "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/decision_log.py"
click node_scorecard "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/scorecard.py"
click node_dashboard "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/dashboard.py"
click node_attribution "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/attribution.py"
click node_prices "https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/prices.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_universe,node_screen,node_factsheet,node_valuation toneBlue
class node_claude,node_weekly,node_weeklyscan,node_entryresearch toneAmber
class node_portfolio,node_risk,node_regime,node_funding,node_corpactions toneMint
class node_entrywatch,node_dipradar,node_decisionslog,node_scorecard,node_dashboard,node_attribution toneRose
class node_datafetch,node_prices,node_market,node_owner,node_benchmark toneIndigo
```

## Components

### Research and screening

- [Stock universe](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/universe.py): `scripts/universe.py`
- [Weekly screen](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/screen.py): `scripts/screen.py`
- [Fact sheets](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/fact_sheet.py): `scripts/fact_sheet.py`
- [Fair valuation](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/valuation.py): `scripts/valuation.py`

### Review and decisions

- [Claude agents](https://github.com/oskarajaspinall-cell/paper-portfolio/tree/main/.claude/agents): `.claude/agents`
- [Weekly workflow](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/weekly_run.py): `scripts/weekly_run.py`
- [Holding review](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/weekly_scan.py): `scripts/weekly_scan.py`
- [Entry research](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/entry_research.py): `scripts/entry_research.py`

### Portfolio operations

- [Portfolio engine](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/portfolio.py): `scripts/portfolio.py`
- [Position sizing](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/risk.py): `scripts/risk.py`
- [Macro regime](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/regime.py): `scripts/regime.py`
- [Funding queue](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/funding_queue.py): `scripts/funding_queue.py`
- [Corporate actions](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/corporate_actions.py): `scripts/corporate_actions.py`

### Monitoring and reporting

- [Entry watch](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/entry_watch.py): `scripts/entry_watch.py`
- [Dip radar](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/dip_radar.py): `scripts/dip_radar.py`
- [Decision log](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/decision_log.py): `scripts/decision_log.py`
- [Decision scorecard](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/scorecard.py): `scripts/scorecard.py`
- [Live dashboard](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/dashboard.py): `scripts/dashboard.py`
- [Return attribution](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/attribution.py): `scripts/attribution.py`

### Market data

- [Fundamental data](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/fetch_data.py): `scripts/fetch_data.py`
- [Portfolio prices](https://github.com/oskarajaspinall-cell/paper-portfolio/blob/main/scripts/prices.py): `scripts/prices.py`
- **Market data services**

### Other components

- **Portfolio owner**
- **S&P 500 benchmark**

## Connections

- Portfolio owner → Weekly workflow: runs review (evidence: `README.md`)
- Weekly workflow → Portfolio engine: fills orders (evidence: `README.md`)
- Weekly workflow → Holding review: checks holdings (evidence: `README.md`)
- Weekly workflow → Weekly screen: runs screen (evidence: `README.md`)
- Weekly screen → Stock universe: ranks universe (evidence: `scripts/screen.py`)
- Weekly screen → Fundamental data: reads fundamentals (evidence: `scripts/screen.py`)
- Weekly screen → Fact sheets: deep dives (evidence: `scripts/screen.py`)
- Fact sheets → Fundamental data: reads company data (evidence: `scripts/fact_sheet.py`)
- Fact sheets → Fair valuation: requests fair value (evidence: `scripts/fact_sheet.py`)
- Weekly workflow → Claude agents: starts agent sessions (evidence: `scripts/weekly_run.py`)
- Claude agents → Entry research: researches candidates (evidence: `README.md`)
- Weekly workflow → Decision log: records decisions (evidence: `README.md`)
- Weekly workflow → Portfolio engine: submits orders (evidence: `README.md`)
- Portfolio engine → Position sizing: sizes positions (evidence: `scripts/portfolio.py`)
- Portfolio engine → Portfolio prices: gets quotes (evidence: `scripts/portfolio.py`)
- Portfolio engine → Macro regime: uses cash reserve (evidence: `scripts/portfolio.py`)
- Portfolio engine → Funding queue: queues blocked buys (evidence: `scripts/funding_queue.py`)
- Portfolio engine → Corporate actions: applies adjustments (evidence: `scripts/corporate_actions.py`)
- Macro regime → Market data services: reads macro indicators (evidence: `scripts/regime.py`)
- Portfolio prices → Market data services: fetches price history (evidence: `scripts/prices.py`)
- Weekly workflow → Entry watch: checks entry hits (evidence: `README.md`)
- Weekly workflow → Dip radar: runs dip radar (evidence: `README.md`)
- Entry watch → Entry research: flags hit stocks (evidence: `README.md`)
- Dip radar → Entry research: flags dip signals (evidence: `README.md`)
- Weekly workflow → Decision scorecard: checks evaluations (evidence: `scripts/weekly_run.py`)
- Weekly workflow → Live dashboard: refreshes dashboard (evidence: `README.md`)
- Weekly workflow → Return attribution: reports returns (evidence: `README.md`)
- Decision log → S&P 500 benchmark: scores against (evidence: `scripts/decision_log.py`)
- Portfolio owner → Live dashboard: views portfolio (evidence: `README.md`)