# joshhheo/s-p500_risk architecture

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

- Interactive diagram: https://gitdiagram.com/joshhheo/s-p500_risk
- Repository: https://github.com/joshhheo/s-p500_risk

## Overview

This repository’s implemented workflow builds an S&P 500 debt-to-assets dataset: it obtains company and sector metadata, pulls SEC financials, records liability availability and calculation methods, computes ratios, then loads company and financial records into a database and refreshes a sector-leverage view. The README also names interest coverage and current ratios, but the sampled implementation shows only debt-to-assets. Edges follow the visible orchestrator and sampled calls; unsampled merge behavior is left unspecified.

Main entry points: [`src/main.py`](https://github.com/joshhheo/s-p500_risk/blob/main/src/main.py) (Pipeline runner), [`src/sec_pull.py`](https://github.com/joshhheo/s-p500_risk/blob/main/src/sec_pull.py) (SEC financial pull), [`src/calculate_debt_to_assets_ratio.py`](https://github.com/joshhheo/s-p500_risk/blob/main/src/calculate_debt_to_assets_ratio.py) (Debt-assets calculation), [`src/companies_table_info.py`](https://github.com/joshhheo/s-p500_risk/blob/main/src/companies_table_info.py) (Company records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Company and SEC Data"]
  node_wiki["Company universe<br/>[wiki_pull.py]"]
  node_identity["SEC identity setup<br/>[setup_sec.py]"]
  node_sec_pull["SEC financial pull<br/>[sec_pull.py]"]
  node_status["Filing status data"]
end

subgraph group_calculation["Ratio Processing"]
  node_main["Pipeline runner<br/>[main.py]"]
  node_calculate["Debt-assets calculation"]
  node_ratios["Ratio results"]
  node_merge["CSV merge<br/>[merge_csv_info.py]"]
end

subgraph group_persistence["Database and View"]
  node_schema["Table creation<br/>[create_tables.py]"]
  node_companies["Company records"]
  node_financials["Financial records"]
  node_database[("Relational database")]
  node_refresh["View refresh<br/>[read_sql.py]"]
  node_view_sql["Sector leverage SQL"]
end

node_investors(("Equity investors"))
node_wikipedia["Wikipedia"]
node_edgar["SEC EDGAR"]

node_investors -.->|"runs pipeline"| node_main
node_main -->|"runs pull"| node_sec_pull
node_sec_pull -->|"gets tickers"| node_wiki
node_wiki -->|"fetches company table"| node_wikipedia
node_sec_pull -->|"sets identity"| node_identity
node_sec_pull -->|"requests financials"| node_edgar
node_sec_pull -->|"writes status"| node_status
node_main -->|"runs calculation"| node_calculate
node_calculate -->|"sets identity"| node_identity
node_calculate -->|"reads status"| node_status
node_calculate -->|"requests financials"| node_edgar
node_calculate -->|"writes ratios"| node_ratios
node_main -->|"runs merge"| node_merge
node_main -->|"creates tables"| node_schema
node_schema -->|"creates tables"| node_database
node_main -->|"loads companies"| node_companies
node_companies -->|"gets company data"| node_wiki
node_companies -->|"upserts companies"| node_database
node_main -->|"loads financials"| node_financials
node_financials -->|"reads ratios"| node_ratios
node_financials -->|"upserts financials"| node_database
node_main -->|"refreshes view"| node_refresh
node_refresh -->|"reads query"| node_view_sql
node_refresh -->|"executes query"| node_database

click node_main "https://github.com/joshhheo/s-p500_risk/blob/main/src/main.py"
click node_wiki "https://github.com/joshhheo/s-p500_risk/blob/main/src/wiki_pull.py"
click node_identity "https://github.com/joshhheo/s-p500_risk/blob/main/src/setup_sec.py"
click node_sec_pull "https://github.com/joshhheo/s-p500_risk/blob/main/src/sec_pull.py"
click node_status "https://github.com/joshhheo/s-p500_risk/blob/main/data/raw/debt_to_assets_status.csv"
click node_calculate "https://github.com/joshhheo/s-p500_risk/blob/main/src/calculate_debt_to_assets_ratio.py"
click node_ratios "https://github.com/joshhheo/s-p500_risk/blob/main/data/processed/debt_to_assets_ratios.csv"
click node_merge "https://github.com/joshhheo/s-p500_risk/blob/main/src/merge_csv_info.py"
click node_schema "https://github.com/joshhheo/s-p500_risk/blob/main/src/create_tables.py"
click node_companies "https://github.com/joshhheo/s-p500_risk/blob/main/src/companies_table_info.py"
click node_financials "https://github.com/joshhheo/s-p500_risk/blob/main/src/financials_table_info.py"
click node_refresh "https://github.com/joshhheo/s-p500_risk/blob/main/src/read_sql.py"
click node_view_sql "https://github.com/joshhheo/s-p500_risk/blob/main/sql/sector_leverage.sql"

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_wiki,node_identity,node_sec_pull,node_status toneBlue
class node_main,node_calculate,node_ratios,node_merge toneAmber
class node_schema,node_companies,node_financials,node_database,node_refresh,node_view_sql toneMint
class node_investors,node_wikipedia,node_edgar toneIndigo
```

## Components

### Company and SEC Data

- [Company universe](https://github.com/joshhheo/s-p500_risk/blob/main/src/wiki_pull.py): `src/wiki_pull.py`
- [SEC identity setup](https://github.com/joshhheo/s-p500_risk/blob/main/src/setup_sec.py): `src/setup_sec.py`
- [SEC financial pull](https://github.com/joshhheo/s-p500_risk/blob/main/src/sec_pull.py): `src/sec_pull.py`
- [Filing status data](https://github.com/joshhheo/s-p500_risk/blob/main/data/raw/debt_to_assets_status.csv): `data/raw/debt_to_assets_status.csv`

### Ratio Processing

- [Pipeline runner](https://github.com/joshhheo/s-p500_risk/blob/main/src/main.py): `src/main.py`
- [Debt-assets calculation](https://github.com/joshhheo/s-p500_risk/blob/main/src/calculate_debt_to_assets_ratio.py): `src/calculate_debt_to_assets_ratio.py`
- [Ratio results](https://github.com/joshhheo/s-p500_risk/blob/main/data/processed/debt_to_assets_ratios.csv): `data/processed/debt_to_assets_ratios.csv`
- [CSV merge](https://github.com/joshhheo/s-p500_risk/blob/main/src/merge_csv_info.py): `src/merge_csv_info.py`

### Database and View

- [Table creation](https://github.com/joshhheo/s-p500_risk/blob/main/src/create_tables.py): `src/create_tables.py`
- [Company records](https://github.com/joshhheo/s-p500_risk/blob/main/src/companies_table_info.py): `src/companies_table_info.py`
- [Financial records](https://github.com/joshhheo/s-p500_risk/blob/main/src/financials_table_info.py): `src/financials_table_info.py`
- **Relational database**
- [View refresh](https://github.com/joshhheo/s-p500_risk/blob/main/src/read_sql.py): `src/read_sql.py`
- [Sector leverage SQL](https://github.com/joshhheo/s-p500_risk/blob/main/sql/sector_leverage.sql): `sql/sector_leverage.sql`

### Other components

- **Equity investors**
- **Wikipedia**
- **SEC EDGAR**

## Connections

- Equity investors → Pipeline runner: runs pipeline
- Pipeline runner → SEC financial pull: runs pull (evidence: `src/main.py`)
- SEC financial pull → Company universe: gets tickers (evidence: `src/sec_pull.py`)
- Company universe → Wikipedia: fetches company table (evidence: `src/wiki_pull.py`)
- SEC financial pull → SEC identity setup: sets identity (evidence: `src/sec_pull.py`)
- SEC financial pull → SEC EDGAR: requests financials (evidence: `src/sec_pull.py`)
- SEC financial pull → Filing status data: writes status (evidence: `src/sec_pull.py`)
- Pipeline runner → Debt-assets calculation: runs calculation (evidence: `src/main.py`)
- Debt-assets calculation → SEC identity setup: sets identity (evidence: `src/calculate_debt_to_assets_ratio.py`)
- Debt-assets calculation → Filing status data: reads status (evidence: `src/calculate_debt_to_assets_ratio.py`)
- Debt-assets calculation → SEC EDGAR: requests financials (evidence: `src/calculate_debt_to_assets_ratio.py`)
- Debt-assets calculation → Ratio results: writes ratios (evidence: `src/calculate_debt_to_assets_ratio.py`)
- Pipeline runner → CSV merge: runs merge (evidence: `src/main.py`)
- Pipeline runner → Table creation: creates tables (evidence: `src/main.py`)
- Table creation → Relational database: creates tables (evidence: `src/create_tables.py`)
- Pipeline runner → Company records: loads companies (evidence: `src/main.py`)
- Company records → Company universe: gets company data (evidence: `src/companies_table_info.py`)
- Company records → Relational database: upserts companies (evidence: `src/companies_table_info.py`)
- Pipeline runner → Financial records: loads financials (evidence: `src/main.py`)
- Financial records → Ratio results: reads ratios (evidence: `src/financials_table_info.py`)
- Financial records → Relational database: upserts financials (evidence: `src/financials_table_info.py`)
- Pipeline runner → View refresh: refreshes view (evidence: `src/main.py`)
- View refresh → Sector leverage SQL: reads query (evidence: `src/read_sql.py`)
- View refresh → Relational database: executes query (evidence: `src/read_sql.py`)
