# aktreides44/stocklenz architecture

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

- Interactive diagram: https://gitdiagram.com/aktreides44/stocklenz
- Repository: https://github.com/aktreides44/stocklenz

## Overview

StockLens turns SEC filings and market prices into a local SQLite dataset, serves that dataset through a read-only API, and presents it in a Flutter screener and company-detail app. The daily refresh coordinates the main data stages; the API separately refreshes its hosted database copy and reads it for requests. The app’s documented capabilities include filtering, sorting, presets, watchlists, configurable columns, scores, and price charts. Flutter internals and several pipeline implementations were not excerpted, so their relationships are shown only where documented or indexed.

Main entry points: [`backend/pipeline/refresh.py`](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/refresh.py) (Data refresh), [`app/lib/screener_page.dart`](https://github.com/aktreides44/stocklenz/blob/main/app/lib/screener_page.dart) (Screener views), [`backend/pipeline/db.py`](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/db.py) (Database storage), [`backend/api/main.py`](https://github.com/aktreides44/stocklenz/blob/main/backend/api/main.py) (API endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data pipeline"]
  node_refresh["Data refresh<br/>[refresh.py]"]
  node_secclient["SEC client<br/>[sec_client.py]"]
  node_filingcheck["Filing updates<br/>[sec_updates.py]"]
  node_extract["Filing extraction<br/>[extract.py]"]
  node_ttm["TTM figures<br/>[ttm.py]"]
  node_shares["Share counts<br/>[shares.py]"]
  node_prices["Latest prices<br/>[prices.py]"]
  node_pricehistory["Price history<br/>[price_history.py]"]
  node_metrics["Metric formulas<br/>[metrics.py]"]
  node_scores["Company scores<br/>[scores.py]"]
  node_analysis["Pros and cons<br/>[analysis.py]"]
  node_dbwriter[("Database storage<br/>[db.py]")]
  node_sqlite[("Stock database")]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_api["Read API"]
  node_apiapp["API endpoints<br/>[main.py]"]
  node_dbrefresh["Database download<br/>[database_file.py]"]
end

subgraph group_app["Flutter app"]
  node_screener["Screener views<br/>[screener_page.dart]"]
  node_company["Company details<br/>[company_page.dart]"]
  node_search["Company search"]
  node_filters["Filters and presets<br/>[filters_panel.dart]"]
  node_columns["Column chooser"]
  node_watchlist["Watchlist<br/>[watchlist.dart]"]
  node_charts["Price chart<br/>[price_chart.dart]"]
  node_scoresview["Score display<br/>[scores_view.dart]"]
end

subgraph group_sources["External sources"]
  node_polygon["Polygon prices"]
  node_yahoo["Yahoo prices"]
  node_sec["SEC EDGAR"]
  node_githubdata["Published database"]
end

node_operator(("Investor"))

node_operator -->|"uses"| node_screener
node_refresh -->|"checks filings"| node_filingcheck
node_refresh -->|"loads filings"| node_secclient
node_refresh -->|"extracts data"| node_extract
node_refresh -->|"derives TTM"| node_ttm
node_refresh -->|"gets shares"| node_shares
node_refresh -->|"gets prices"| node_prices
node_refresh -->|"updates history"| node_pricehistory
node_refresh -->|"calculates metrics"| node_metrics
node_refresh -->|"adds scores"| node_scores
node_refresh -->|"writes database"| node_dbwriter
node_secclient -->|"downloads filings"| node_sec
node_prices -->|"requests prices"| node_polygon
node_prices -.->|"backs up gaps"| node_yahoo
node_dbwriter -->|"uses rules"| node_analysis
node_dbwriter -->|"uses formulas"| node_metrics
node_dbwriter -->|"stores records"| node_sqlite
node_apiapp -->|"refreshes copy"| node_dbrefresh
node_apiapp -->|"reads data"| node_dbwriter
node_dbrefresh -->|"downloads database"| node_githubdata
node_apiapp -->|"serves screener data"| node_screener
node_apiapp -->|"serves detail data"| node_company
node_screener -.->|"filters companies"| node_filters
node_screener -.->|"configures columns"| node_columns
node_screener -.->|"shows watchlist"| node_watchlist
node_screener -.->|"opens lookup"| node_search
node_company -.->|"shows prices"| node_charts
node_company -.->|"shows scores"| node_scoresview

click node_refresh "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/refresh.py"
click node_secclient "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/sec_client.py"
click node_filingcheck "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/sec_updates.py"
click node_extract "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/extract.py"
click node_ttm "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/ttm.py"
click node_shares "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/shares.py"
click node_prices "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/prices.py"
click node_pricehistory "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/price_history.py"
click node_metrics "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/metrics.py"
click node_scores "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/scores.py"
click node_analysis "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/analysis.py"
click node_dbwriter "https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/db.py"
click node_config "https://github.com/aktreides44/stocklenz/blob/main/backend/config.py"
click node_apiapp "https://github.com/aktreides44/stocklenz/blob/main/backend/api/main.py"
click node_dbrefresh "https://github.com/aktreides44/stocklenz/blob/main/backend/api/database_file.py"
click node_screener "https://github.com/aktreides44/stocklenz/blob/main/app/lib/screener_page.dart"
click node_company "https://github.com/aktreides44/stocklenz/blob/main/app/lib/company_page.dart"
click node_search "https://github.com/aktreides44/stocklenz/blob/main/app/lib/company_search.dart"
click node_filters "https://github.com/aktreides44/stocklenz/blob/main/app/lib/filters_panel.dart"
click node_columns "https://github.com/aktreides44/stocklenz/blob/main/app/lib/columns_dialog.dart"
click node_watchlist "https://github.com/aktreides44/stocklenz/blob/main/app/lib/watchlist.dart"
click node_charts "https://github.com/aktreides44/stocklenz/blob/main/app/lib/price_chart.dart"
click node_scoresview "https://github.com/aktreides44/stocklenz/blob/main/app/lib/scores_view.dart"

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_refresh,node_secclient,node_filingcheck,node_extract,node_ttm,node_shares,node_prices,node_pricehistory,node_metrics,node_scores,node_analysis,node_dbwriter,node_sqlite,node_config toneBlue
class node_apiapp,node_dbrefresh toneAmber
class node_screener,node_company,node_search,node_filters,node_columns,node_watchlist,node_charts,node_scoresview toneMint
class node_polygon,node_yahoo,node_sec,node_githubdata toneRose
class node_operator toneIndigo
```

## Components

### Data pipeline

- [Data refresh](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/refresh.py): `backend/pipeline/refresh.py`
- [SEC client](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/sec_client.py): `backend/pipeline/sec_client.py`
- [Filing updates](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/sec_updates.py): `backend/pipeline/sec_updates.py`
- [Filing extraction](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/extract.py): `backend/pipeline/extract.py`
- [TTM figures](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/ttm.py): `backend/pipeline/ttm.py`
- [Share counts](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/shares.py): `backend/pipeline/shares.py`
- [Latest prices](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/prices.py): `backend/pipeline/prices.py`
- [Price history](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/price_history.py): `backend/pipeline/price_history.py`
- [Metric formulas](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/metrics.py): `backend/pipeline/metrics.py`
- [Company scores](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/scores.py): `backend/pipeline/scores.py`
- [Pros and cons](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/analysis.py): `backend/pipeline/analysis.py`
- [Database storage](https://github.com/aktreides44/stocklenz/blob/main/backend/pipeline/db.py): `backend/pipeline/db.py`
- **Stock database**
- [Runtime settings](https://github.com/aktreides44/stocklenz/blob/main/backend/config.py): `backend/config.py`

### Read API

- [API endpoints](https://github.com/aktreides44/stocklenz/blob/main/backend/api/main.py): `backend/api/main.py`
- [Database download](https://github.com/aktreides44/stocklenz/blob/main/backend/api/database_file.py): `backend/api/database_file.py`

### Flutter app

- [Screener views](https://github.com/aktreides44/stocklenz/blob/main/app/lib/screener_page.dart): `app/lib/screener_page.dart`
- [Company details](https://github.com/aktreides44/stocklenz/blob/main/app/lib/company_page.dart): `app/lib/company_page.dart`
- [Company search](https://github.com/aktreides44/stocklenz/blob/main/app/lib/company_search.dart): `app/lib/company_search.dart`
- [Filters and presets](https://github.com/aktreides44/stocklenz/blob/main/app/lib/filters_panel.dart): `app/lib/filters_panel.dart`
- [Column chooser](https://github.com/aktreides44/stocklenz/blob/main/app/lib/columns_dialog.dart): `app/lib/columns_dialog.dart`
- [Watchlist](https://github.com/aktreides44/stocklenz/blob/main/app/lib/watchlist.dart): `app/lib/watchlist.dart`
- [Price chart](https://github.com/aktreides44/stocklenz/blob/main/app/lib/price_chart.dart): `app/lib/price_chart.dart`
- [Score display](https://github.com/aktreides44/stocklenz/blob/main/app/lib/scores_view.dart): `app/lib/scores_view.dart`

### External sources

- **Polygon prices**
- **Yahoo prices**
- **SEC EDGAR**
- **Published database**

### Other components

- **Investor**

## Connections

- Investor → Screener views: uses (evidence: `README.md`)
- Data refresh → Filing updates: checks filings (evidence: `backend/pipeline/refresh.py`)
- Data refresh → SEC client: loads filings (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Filing extraction: extracts data (evidence: `backend/pipeline/refresh.py`)
- Data refresh → TTM figures: derives TTM (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Share counts: gets shares (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Latest prices: gets prices (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Price history: updates history (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Metric formulas: calculates metrics (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Company scores: adds scores (evidence: `backend/pipeline/refresh.py`)
- Data refresh → Database storage: writes database (evidence: `backend/pipeline/refresh.py`)
- SEC client → SEC EDGAR: downloads filings (evidence: `backend/pipeline/sec_client.py`)
- Latest prices → Polygon prices: requests prices (evidence: `README.md`)
- Latest prices → Yahoo prices: backs up gaps (evidence: `README.md`)
- Database storage → Pros and cons: uses rules (evidence: `backend/pipeline/db.py`)
- Database storage → Metric formulas: uses formulas (evidence: `backend/pipeline/db.py`)
- Database storage → Stock database: stores records (evidence: `README.md`)
- API endpoints → Database download: refreshes copy (evidence: `backend/api/main.py`)
- API endpoints → Database storage: reads data (evidence: `backend/api/main.py`)
- Database download → Published database: downloads database (evidence: `backend/api/database_file.py`)
- API endpoints → Screener views: serves screener data (evidence: `README.md`)
- API endpoints → Company details: serves detail data (evidence: `README.md`)
- Screener views → Filters and presets: filters companies
- Screener views → Column chooser: configures columns
- Screener views → Watchlist: shows watchlist
- Screener views → Company search: opens lookup
- Company details → Price chart: shows prices
- Company details → Score display: shows scores