# inthiiii/lak-arthika architecture

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

- Interactive diagram: https://gitdiagram.com/inthiiii/lak-arthika
- Repository: https://github.com/inthiiii/lak-arthika

## Overview

LakArthika is a Sri Lankan market-intelligence digital twin: official HARTI bulletins become validated historical price data, then feed an API and public dashboard, alongside forecasting and economic-stress analysis. Historical ingestion, forecasting, external signals, stress scoring, and dashboard presentation are distinct product branches. The README documents the broader data lifecycle and capabilities; sampled source excerpts and the SOURCE INDEX support only some implementation links, so unsampled relationships are not asserted.

Main entry points: [`src/lak_arthika/pipelines/harti_historical.py`](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/pipelines/harti_historical.py) (Historical workflow), [`src/lak_arthika/forecasting/trainer.py`](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/trainer.py) (Forecast training), [`src/lak_arthika/api.py`](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/api.py) (FastAPI service), [`src/lak_arthika/storage/analytics.py`](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/analytics.py) (DuckDB analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Price ingestion"]
  node_historical["Historical workflow"]
  node_harti_fetch["HARTI retrieval<br/>[harti.py]"]
  node_archive_fetch["Archive downloads<br/>[harti_archive.py]"]
  node_parser["Versioned parsers<br/>[harti_v1.py]"]
  node_price_contract["Price records<br/>[price.py]"]
end

subgraph group_data["Data and analytics"]
  node_manifest[("Bulletin manifest<br/>[manifest.py]")]
  node_quality["Quality gate<br/>[quality.py]"]
  node_price_store[("Price storage<br/>[historical.py]")]
  node_analytics[("DuckDB analytics<br/>[analytics.py]")]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_models["Forecasting and signals"]
  node_forecast["Forecast training<br/>[trainer.py]"]
  node_features["Price features<br/>[price_features.py]"]
  node_evaluation["Backtests and metrics<br/>[backtest.py]"]
  node_artifacts[("Model artifacts<br/>[artifacts.py]")]
  node_signal_sources["Weather and official signals"]
  node_signal_store[("Signal storage<br/>[signals.py]")]
  node_model_health["Model health<br/>[health.py]"]
end

subgraph group_stress["Economic stress"]
  node_stress_engine["Stress engine<br/>[engine.py]"]
  node_stress_store[("Stress records<br/>[stress.py]")]
  node_stress_contract["Stress contracts<br/>[stress.py]"]
  node_stress_methods["Scoring and alerts"]
end

subgraph group_experience["API and dashboard"]
  node_api["FastAPI service<br/>[api.py]"]
  node_dashboard["Dashboard application<br/>[App.tsx]"]
  node_api_queries["Dashboard queries<br/>[queries.ts]"]
  node_filters["Shareable filters"]
  node_market_views["Market and stress views<br/>[MarketMap.tsx]"]
end

node_harti(("HARTI archive"))
node_external_user(("Dashboard user"))

node_harti -->|"provides bulletins"| node_historical
node_historical -->|"discovers and downloads"| node_archive_fetch
node_historical -->|"preserves files"| node_harti_fetch
node_historical -->|"selects parser"| node_parser
node_harti_fetch -->|"creates records"| node_price_contract
node_historical -->|"updates manifest"| node_manifest
node_historical -->|"validates records"| node_quality
node_historical -->|"publishes prices"| node_price_store
node_historical -->|"builds analytics"| node_analytics
node_historical -->|"retrieves bulletins"| node_harti_fetch
node_analytics -->|"serves price data"| node_api
node_manifest -->|"supplies quality status"| node_api
node_analytics -->|"provides history"| node_forecast
node_forecast -->|"builds features"| node_features
node_forecast -->|"evaluates horizons"| node_evaluation
node_forecast -->|"publishes model"| node_artifacts
node_signal_sources -.->|"stores observations"| node_signal_store
node_signal_store -->|"provides point-in-time signals"| node_forecast
node_signal_store -->|"checks freshness"| node_model_health
node_artifacts -->|"checks promoted model"| node_model_health
node_analytics -->|"provides price history"| node_stress_engine
node_stress_engine -->|"runs scoring and alerts"| node_stress_methods
node_stress_engine -->|"writes results"| node_stress_store
node_stress_engine -->|"builds signals"| node_stress_contract
node_stress_store -->|"serves stress results"| node_api
node_artifacts -->|"serves forecasts"| node_api
node_api -->|"responds to requests"| node_api_queries
node_api_queries -->|"provides query data"| node_dashboard
node_dashboard -->|"reads and updates"| node_filters
node_dashboard -->|"renders market views"| node_market_views
node_external_user -->|"explores markets"| node_dashboard

click node_historical "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/pipelines/harti_historical.py"
click node_harti_fetch "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/harti.py"
click node_archive_fetch "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/harti_archive.py"
click node_parser "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/parsers/harti_v1.py"
click node_price_contract "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/models/price.py"
click node_manifest "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/manifest.py"
click node_quality "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/quality.py"
click node_price_store "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/historical.py"
click node_analytics "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/analytics.py"
click node_config "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/config.py"
click node_forecast "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/trainer.py"
click node_features "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/features/price_features.py"
click node_evaluation "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/evaluation/backtest.py"
click node_artifacts "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/artifacts.py"
click node_signal_sources "https://github.com/inthiiii/lak-arthika/tree/main/src/lak_arthika/signals"
click node_signal_store "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/signals.py"
click node_model_health "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/health.py"
click node_stress_engine "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/stress/engine.py"
click node_stress_store "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/stress.py"
click node_stress_contract "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/models/stress.py"
click node_stress_methods "https://github.com/inthiiii/lak-arthika/tree/main/src/lak_arthika/stress"
click node_api "https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/api.py"
click node_dashboard "https://github.com/inthiiii/lak-arthika/blob/main/web/src/App.tsx"
click node_api_queries "https://github.com/inthiiii/lak-arthika/blob/main/web/src/api/queries.ts"
click node_filters "https://github.com/inthiiii/lak-arthika/blob/main/web/src/hooks/useDashboardFilters.ts"
click node_market_views "https://github.com/inthiiii/lak-arthika/blob/main/web/src/components/MarketMap.tsx"

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_historical,node_harti_fetch,node_archive_fetch,node_parser,node_price_contract,node_external_user toneBlue
class node_manifest,node_quality,node_price_store,node_analytics,node_config toneAmber
class node_forecast,node_features,node_evaluation,node_artifacts,node_signal_sources,node_signal_store,node_model_health toneMint
class node_stress_engine,node_stress_store,node_stress_contract,node_stress_methods toneRose
class node_api,node_dashboard,node_api_queries,node_filters,node_market_views,node_harti toneIndigo
```

## Components

### Price ingestion

- [Historical workflow](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/pipelines/harti_historical.py): `src/lak_arthika/pipelines/harti_historical.py`
- [HARTI retrieval](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/harti.py): `src/lak_arthika/ingestion/harti.py`
- [Archive downloads](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/harti_archive.py): `src/lak_arthika/ingestion/harti_archive.py`
- [Versioned parsers](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/ingestion/parsers/harti_v1.py): `src/lak_arthika/ingestion/parsers/harti_v1.py`
- [Price records](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/models/price.py): `src/lak_arthika/models/price.py`

### Data and analytics

- [Bulletin manifest](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/manifest.py): `src/lak_arthika/storage/manifest.py`
- [Quality gate](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/quality.py): `src/lak_arthika/quality.py`
- [Price storage](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/historical.py): `src/lak_arthika/storage/historical.py`
- [DuckDB analytics](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/analytics.py): `src/lak_arthika/storage/analytics.py`
- [Runtime settings](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/config.py): `src/lak_arthika/config.py`

### Forecasting and signals

- [Forecast training](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/trainer.py): `src/lak_arthika/forecasting/trainer.py`
- [Price features](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/features/price_features.py): `src/lak_arthika/features/price_features.py`
- [Backtests and metrics](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/evaluation/backtest.py): `src/lak_arthika/evaluation/backtest.py`
- [Model artifacts](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/artifacts.py): `src/lak_arthika/forecasting/artifacts.py`
- [Weather and official signals](https://github.com/inthiiii/lak-arthika/tree/main/src/lak_arthika/signals): `src/lak_arthika/signals`
- [Signal storage](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/signals.py): `src/lak_arthika/storage/signals.py`
- [Model health](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/forecasting/health.py): `src/lak_arthika/forecasting/health.py`

### Economic stress

- [Stress engine](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/stress/engine.py): `src/lak_arthika/stress/engine.py`
- [Stress records](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/storage/stress.py): `src/lak_arthika/storage/stress.py`
- [Stress contracts](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/models/stress.py): `src/lak_arthika/models/stress.py`
- [Scoring and alerts](https://github.com/inthiiii/lak-arthika/tree/main/src/lak_arthika/stress): `src/lak_arthika/stress`

### API and dashboard

- [FastAPI service](https://github.com/inthiiii/lak-arthika/blob/main/src/lak_arthika/api.py): `src/lak_arthika/api.py`
- [Dashboard application](https://github.com/inthiiii/lak-arthika/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Dashboard queries](https://github.com/inthiiii/lak-arthika/blob/main/web/src/api/queries.ts): `web/src/api/queries.ts`
- [Shareable filters](https://github.com/inthiiii/lak-arthika/blob/main/web/src/hooks/useDashboardFilters.ts): `web/src/hooks/useDashboardFilters.ts`
- [Market and stress views](https://github.com/inthiiii/lak-arthika/blob/main/web/src/components/MarketMap.tsx): `web/src/components/MarketMap.tsx`

### Other components

- **HARTI archive**
- **Dashboard user**

## Connections

- HARTI archive → Historical workflow: provides bulletins (evidence: `README.md`)
- Historical workflow → Archive downloads: discovers and downloads (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → HARTI retrieval: preserves files (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → Versioned parsers: selects parser (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- HARTI retrieval → Price records: creates records (evidence: `src/lak_arthika/ingestion/harti.py`)
- Historical workflow → Bulletin manifest: updates manifest (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → Quality gate: validates records (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → Price storage: publishes prices (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → DuckDB analytics: builds analytics (evidence: `src/lak_arthika/pipelines/harti_historical.py`)
- Historical workflow → HARTI retrieval: retrieves bulletins (evidence: `README.md`)
- DuckDB analytics → FastAPI service: serves price data (evidence: `src/lak_arthika/api.py`)
- Bulletin manifest → FastAPI service: supplies quality status (evidence: `src/lak_arthika/api.py`)
- DuckDB analytics → Forecast training: provides history (evidence: `README.md`)
- Forecast training → Price features: builds features (evidence: `src/lak_arthika/forecasting/trainer.py`)
- Forecast training → Backtests and metrics: evaluates horizons (evidence: `src/lak_arthika/forecasting/trainer.py`)
- Forecast training → Model artifacts: publishes model (evidence: `README.md`)
- Weather and official signals → Signal storage: stores observations
- Signal storage → Forecast training: provides point-in-time signals (evidence: `src/lak_arthika/forecasting/trainer.py`)
- Signal storage → Model health: checks freshness (evidence: `src/lak_arthika/forecasting/health.py`)
- Model artifacts → Model health: checks promoted model (evidence: `src/lak_arthika/forecasting/health.py`)
- DuckDB analytics → Stress engine: provides price history (evidence: `README.md`)
- Stress engine → Scoring and alerts: runs scoring and alerts (evidence: `src/lak_arthika/stress/engine.py`)
- Stress engine → Stress records: writes results (evidence: `src/lak_arthika/stress/engine.py`)
- Stress engine → Stress contracts: builds signals (evidence: `src/lak_arthika/stress/engine.py`)
- Stress records → FastAPI service: serves stress results (evidence: `src/lak_arthika/api.py`)
- Model artifacts → FastAPI service: serves forecasts (evidence: `src/lak_arthika/api.py`)
- FastAPI service → Dashboard queries: responds to requests (evidence: `README.md`)
- Dashboard queries → Dashboard application: provides query data (evidence: `web/src/App.tsx`)
- Dashboard application → Shareable filters: reads and updates (evidence: `web/src/App.tsx`)
- Dashboard application → Market and stress views: renders market views (evidence: `web/src/App.tsx`)
- Dashboard user → Dashboard application: explores markets (evidence: `README.md`)
