# hajinhyukson/aat architecture

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

- Interactive diagram: https://gitdiagram.com/hajinhyukson/aat
- Repository: https://github.com/hajinhyukson/aat

## Overview

AAT ingests point-in-time market, macro, factor, and filing data; preserves source snapshots and promotes normalized records; selects security universes and runs attribution backfills; then exposes contribution, residual, evidence, and run summaries through an API and dashboard. The engine includes factor and event evidence, return accounting, residual diagnostics, and confidence scoring. README documents major stages and backfill behavior; sampled source verifies selected adapter, ingestion, database, API, and dashboard links. Unsampled job internals and several subsystem connections are therefore represented only where documented.

Main entry points: [`jobs`](https://github.com/hajinhyukson/aat/tree/main/jobs) (Backfill orchestration), [`engine/contracts.py`](https://github.com/hajinhyukson/aat/blob/main/engine/contracts.py) (Attribution contracts), [`api/main.py`](https://github.com/hajinhyukson/aat/blob/main/api/main.py) (Attribution API), [`db/models.py`](https://github.com/hajinhyukson/aat/blob/main/db/models.py) (Canonical records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Sources and ingestion"]
  node_fmp["FMP prices<br/>[client.py]"]
  node_fred["FRED macro<br/>[client.py]"]
  node_french["French factors<br/>[client.py]"]
  node_edgar["EDGAR filings<br/>[client.py]"]
  node_ingestion["Import jobs"]
end

subgraph group_data["Canonical data"]
  node_staging[("Snapshot staging")]
  node_universe[("Universe and identity<br/>[models.py]")]
  node_canonical[("Canonical records<br/>[models.py]")]
  node_session["Database sessions<br/>[session.py]"]
end

subgraph group_method["Attribution methodology"]
  node_orchestration["Backfill orchestration"]
  node_returns["Return accounting<br/>[accounting.py]"]
  node_factors["Factor models"]
  node_events["Event evidence"]
  node_exposures["Exposure decisions"]
  node_contracts["Attribution contracts<br/>[contracts.py]"]
  node_diagnostics["Residual diagnostics<br/>[diagnostics.py]"]
  node_confidence["Confidence scoring<br/>[scoring.py]"]
end

subgraph group_serve["API and dashboard"]
  node_api["Attribution API<br/>[main.py]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_proxy["Dashboard API proxy<br/>[route.ts]"]
end

node_analyst(("Analyst"))
node_sources(("External sources"))

node_sources -->|"provides prices"| node_fmp
node_sources -->|"provides macro data"| node_fred
node_sources -->|"provides factors"| node_french
node_sources -->|"provides filings"| node_edgar
node_fmp -->|"fetches prices"| node_ingestion
node_fred -->|"fetches observations"| node_ingestion
node_french -->|"fetches factor rows"| node_ingestion
node_edgar -->|"fetches submissions"| node_ingestion
node_ingestion -->|"preserves snapshots"| node_staging
node_ingestion -->|"promotes records"| node_canonical
node_ingestion -->|"builds membership"| node_universe
node_session -->|"commits records"| node_canonical
node_universe -->|"selects securities"| node_orchestration
node_canonical -->|"provides attribution inputs"| node_orchestration
node_orchestration -->|"runs windows"| node_returns
node_orchestration -->|"computes contributions"| node_factors
node_orchestration -->|"uses event evidence"| node_events
node_orchestration -->|"uses mappings"| node_exposures
node_returns -->|"forms results"| node_contracts
node_factors -.->|"emits contributions"| node_contracts
node_events -.->|"supplies evidence"| node_contracts
node_exposures -.->|"gates updates"| node_contracts
node_contracts -->|"evaluates residuals"| node_diagnostics
node_contracts -->|"scores confidence"| node_confidence
node_orchestration -->|"stores attribution"| node_canonical
node_analyst -->|"requests results"| node_api
node_api -->|"queries records"| node_session
node_api -->|"formats diagnostics"| node_diagnostics
node_api -.->|"serves requests"| node_proxy
node_proxy -->|"forwards API data"| node_dashboard

click node_fmp "https://github.com/hajinhyukson/aat/blob/main/adapters/fmp/client.py"
click node_fred "https://github.com/hajinhyukson/aat/blob/main/adapters/fred/client.py"
click node_french "https://github.com/hajinhyukson/aat/blob/main/adapters/french/client.py"
click node_edgar "https://github.com/hajinhyukson/aat/blob/main/adapters/sec_edgar/client.py"
click node_ingestion "https://github.com/hajinhyukson/aat/tree/main/jobs"
click node_staging "https://github.com/hajinhyukson/aat/tree/main/jobs"
click node_universe "https://github.com/hajinhyukson/aat/blob/main/db/models.py"
click node_canonical "https://github.com/hajinhyukson/aat/blob/main/db/models.py"
click node_session "https://github.com/hajinhyukson/aat/blob/main/db/session.py"
click node_orchestration "https://github.com/hajinhyukson/aat/tree/main/jobs"
click node_returns "https://github.com/hajinhyukson/aat/blob/main/engine/returns/accounting.py"
click node_factors "https://github.com/hajinhyukson/aat/tree/main/engine/factors"
click node_events "https://github.com/hajinhyukson/aat/tree/main/engine/events"
click node_exposures "https://github.com/hajinhyukson/aat/tree/main/engine/exposures"
click node_contracts "https://github.com/hajinhyukson/aat/blob/main/engine/contracts.py"
click node_diagnostics "https://github.com/hajinhyukson/aat/blob/main/engine/attribution/diagnostics.py"
click node_confidence "https://github.com/hajinhyukson/aat/blob/main/engine/confidence/scoring.py"
click node_api "https://github.com/hajinhyukson/aat/blob/main/api/main.py"
click node_dashboard "https://github.com/hajinhyukson/aat/blob/main/dashboard/app/page.tsx"
click node_proxy "https://github.com/hajinhyukson/aat/blob/main/dashboard/app/api/aat/%5B...path%5D/route.ts"

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_fmp,node_fred,node_french,node_edgar,node_ingestion toneBlue
class node_staging,node_universe,node_canonical,node_session toneAmber
class node_orchestration,node_returns,node_factors,node_events,node_exposures,node_contracts,node_diagnostics,node_confidence toneMint
class node_api,node_dashboard,node_proxy toneRose
class node_analyst,node_sources toneIndigo
```

## Components

### Sources and ingestion

- [FMP prices](https://github.com/hajinhyukson/aat/blob/main/adapters/fmp/client.py): `adapters/fmp/client.py`
- [FRED macro](https://github.com/hajinhyukson/aat/blob/main/adapters/fred/client.py): `adapters/fred/client.py`
- [French factors](https://github.com/hajinhyukson/aat/blob/main/adapters/french/client.py): `adapters/french/client.py`
- [EDGAR filings](https://github.com/hajinhyukson/aat/blob/main/adapters/sec_edgar/client.py): `adapters/sec_edgar/client.py`
- [Import jobs](https://github.com/hajinhyukson/aat/tree/main/jobs): `jobs`

### Canonical data

- [Snapshot staging](https://github.com/hajinhyukson/aat/tree/main/jobs): `jobs`
- [Universe and identity](https://github.com/hajinhyukson/aat/blob/main/db/models.py): `db/models.py`
- [Canonical records](https://github.com/hajinhyukson/aat/blob/main/db/models.py): `db/models.py`
- [Database sessions](https://github.com/hajinhyukson/aat/blob/main/db/session.py): `db/session.py`

### Attribution methodology

- [Backfill orchestration](https://github.com/hajinhyukson/aat/tree/main/jobs): `jobs`
- [Return accounting](https://github.com/hajinhyukson/aat/blob/main/engine/returns/accounting.py): `engine/returns/accounting.py`
- [Factor models](https://github.com/hajinhyukson/aat/tree/main/engine/factors): `engine/factors`
- [Event evidence](https://github.com/hajinhyukson/aat/tree/main/engine/events): `engine/events`
- [Exposure decisions](https://github.com/hajinhyukson/aat/tree/main/engine/exposures): `engine/exposures`
- [Attribution contracts](https://github.com/hajinhyukson/aat/blob/main/engine/contracts.py): `engine/contracts.py`
- [Residual diagnostics](https://github.com/hajinhyukson/aat/blob/main/engine/attribution/diagnostics.py): `engine/attribution/diagnostics.py`
- [Confidence scoring](https://github.com/hajinhyukson/aat/blob/main/engine/confidence/scoring.py): `engine/confidence/scoring.py`

### API and dashboard

- [Attribution API](https://github.com/hajinhyukson/aat/blob/main/api/main.py): `api/main.py`
- [Dashboard](https://github.com/hajinhyukson/aat/blob/main/dashboard/app/page.tsx): `dashboard/app/page.tsx`
- [Dashboard API proxy](https://github.com/hajinhyukson/aat/blob/main/dashboard/app/api/aat/%5B...path%5D/route.ts): `dashboard/app/api/aat/[...path]/route.ts`

### Other components

- **Analyst**
- **External sources**

## Connections

- External sources → FMP prices: provides prices
- External sources → FRED macro: provides macro data
- External sources → French factors: provides factors
- External sources → EDGAR filings: provides filings
- FMP prices → Import jobs: fetches prices (evidence: `jobs/ingest_fmp_prices.py`)
- FRED macro → Import jobs: fetches observations (evidence: `jobs/ingest_fred_macro.py`)
- French factors → Import jobs: fetches factor rows (evidence: `jobs/ingest_french_factors.py`)
- EDGAR filings → Import jobs: fetches submissions (evidence: `jobs/ingest_edgar_submissions.py`)
- Import jobs → Snapshot staging: preserves snapshots
- Import jobs → Canonical records: promotes records (evidence: `jobs/ingest_fmp_prices.py`)
- Import jobs → Universe and identity: builds membership (evidence: `jobs/ingest_fmp_prices.py`)
- Database sessions → Canonical records: commits records (evidence: `jobs/ingest_fmp_prices.py`)
- Universe and identity → Backfill orchestration: selects securities (evidence: `jobs/ingest_fmp_prices.py`)
- Canonical records → Backfill orchestration: provides attribution inputs (evidence: `jobs/ingest_fmp_prices.py`)
- Backfill orchestration → Return accounting: runs windows
- Backfill orchestration → Factor models: computes contributions
- Backfill orchestration → Event evidence: uses event evidence
- Backfill orchestration → Exposure decisions: uses mappings
- Return accounting → Attribution contracts: forms results (evidence: `engine/returns/accounting.py`)
- Factor models → Attribution contracts: emits contributions (evidence: `engine/factors/hierarchical_model.py`)
- Event evidence → Attribution contracts: supplies evidence (evidence: `engine/events/taxonomy.py`)
- Exposure decisions → Attribution contracts: gates updates (evidence: `engine/exposures/gates.py`)
- Attribution contracts → Residual diagnostics: evaluates residuals (evidence: `engine/attribution/diagnostics.py`)
- Attribution contracts → Confidence scoring: scores confidence (evidence: `engine/confidence/scoring.py`)
- Backfill orchestration → Canonical records: stores attribution (evidence: `jobs/ingest_fmp_prices.py`)
- Analyst → Attribution API: requests results
- Attribution API → Database sessions: queries records (evidence: `api/main.py`)
- Attribution API → Residual diagnostics: formats diagnostics (evidence: `api/main.py`)
- Attribution API → Dashboard API proxy: serves requests
- Dashboard API proxy → Dashboard: forwards API data (evidence: `dashboard/app/api/aat/[...path]/route.ts`)