# psxdata/psxdata-api architecture

> Architecture diagram of the GitHub repository psxdata/psxdata-api, 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/psxdata/psxdata-api
- Repository: https://github.com/psxdata/psxdata-api

## Overview

psxdata-api is a FastAPI service that exposes PSX stock, index, sector, screener, and market data over HTTP. Callers enter through the application’s registered routes; handlers fetch or assemble data, validate it into response envelopes, and return it. Historical stock data follows a separate cache-first path, with freshness rules and optional Redis persistence; proxy passthrough can alter the route to PSX when enabled. The graph reflects the supplied excerpts, SOURCE INDEX references, and README; some subsystem wiring is documented but its implementation was not sampled.

Main entry points: [`api/routers/__init__.py`](https://github.com/psxdata/psxdata-api/blob/main/api/routers/__init__.py) (Route Registry), [`api/proxy.py`](https://github.com/psxdata/psxdata-api/blob/main/api/proxy.py) (Proxy Passthrough), [`api/cache/historical.py`](https://github.com/psxdata/psxdata-api/blob/main/api/cache/historical.py) (History Service), [`api/schemas.py`](https://github.com/psxdata/psxdata-api/blob/main/api/schemas.py) (Response Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_registry["Route Registry<br/>[__init__.py]"]
  node_health["Health Endpoint<br/>[health.py]"]
  node_schemas["Response Models<br/>[schemas.py]"]
end

subgraph group_domain["Market Data"]
  node_stocks["Stock Endpoints<br/>[stocks.py]"]
  node_indices["Index Endpoints<br/>[indices.py]"]
  node_sectors["Sector Endpoints<br/>[sectors.py]"]
  node_screener["Screener Endpoint<br/>[screener.py]"]
  node_market["Market Endpoints<br/>[market.py]"]
end

subgraph group_cache["Historical Cache"]
  node_historical["History Service<br/>[historical.py]"]
  node_freshness["Freshness Rules<br/>[freshness.py]"]
  node_codec["Cache Codec<br/>[codec.py]"]
  node_factory["Cache Factory<br/>[factory.py]"]
  node_tiered["Tiered Store<br/>[store.py]"]
  node_memory["Memory LRU<br/>[store.py]"]
  node_redisstore["Redis Store<br/>[store.py]"]
end

subgraph group_ops["Integrations"]
  node_redis[("Redis Service")]
  node_proxy["Proxy Passthrough<br/>[proxy.py]"]
  node_psx["psxdata SDK"]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

node_caller(("API Caller"))

node_caller -->|"sends request"| node_app
node_app -->|"registers routes"| node_registry
node_registry -->|"registers"| node_health
node_registry -->|"registers"| node_stocks
node_registry -->|"registers"| node_indices
node_registry -->|"registers"| node_sectors
node_registry -->|"registers"| node_screener
node_registry -->|"registers"| node_market
node_stocks -->|"validates responses"| node_schemas
node_indices -->|"validates responses"| node_schemas
node_sectors -->|"validates responses"| node_schemas
node_screener -->|"validates responses"| node_schemas
node_market -->|"validates responses"| node_schemas
node_health -->|"uses models"| node_schemas
node_stocks -->|"gets history"| node_historical
node_stocks -->|"uses PSX source"| node_proxy
node_indices -->|"uses PSX source"| node_proxy
node_sectors -->|"uses PSX source"| node_proxy
node_screener -->|"uses PSX source"| node_proxy
node_market -->|"uses PSX source"| node_proxy
node_proxy -->|"fetches data"| node_psx
node_historical -.->|"fetches on miss"| node_psx
node_historical -->|"reads and writes"| node_tiered
node_historical -->|"checks freshness"| node_freshness
node_historical -->|"encodes entries"| node_codec
node_factory -->|"builds service"| node_historical
node_factory -->|"constructs store"| node_tiered
node_factory -->|"uses default TTL"| node_freshness
node_app -->|"builds cache"| node_factory
node_app -->|"configures passthrough"| node_proxy
node_app -->|"flushes telemetry"| node_telemetry
node_tiered -->|"checks first"| node_memory
node_tiered -->|"falls back"| node_redisstore
node_redisstore -.->|"reads and writes"| node_redis

click node_app "https://github.com/psxdata/psxdata-api/blob/main/api/main.py"
click node_registry "https://github.com/psxdata/psxdata-api/blob/main/api/routers/__init__.py"
click node_health "https://github.com/psxdata/psxdata-api/blob/main/api/routers/health.py"
click node_stocks "https://github.com/psxdata/psxdata-api/blob/main/api/routers/stocks.py"
click node_indices "https://github.com/psxdata/psxdata-api/blob/main/api/routers/indices.py"
click node_sectors "https://github.com/psxdata/psxdata-api/blob/main/api/routers/sectors.py"
click node_screener "https://github.com/psxdata/psxdata-api/blob/main/api/routers/screener.py"
click node_market "https://github.com/psxdata/psxdata-api/blob/main/api/routers/market.py"
click node_schemas "https://github.com/psxdata/psxdata-api/blob/main/api/schemas.py"
click node_historical "https://github.com/psxdata/psxdata-api/blob/main/api/cache/historical.py"
click node_freshness "https://github.com/psxdata/psxdata-api/blob/main/api/cache/freshness.py"
click node_codec "https://github.com/psxdata/psxdata-api/blob/main/api/cache/codec.py"
click node_factory "https://github.com/psxdata/psxdata-api/blob/main/api/cache/factory.py"
click node_tiered "https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py"
click node_memory "https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py"
click node_redisstore "https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py"
click node_proxy "https://github.com/psxdata/psxdata-api/blob/main/api/proxy.py"
click node_telemetry "https://github.com/psxdata/psxdata-api/blob/main/api/telemetry.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_app,node_registry,node_health,node_schemas toneBlue
class node_stocks,node_indices,node_sectors,node_screener,node_market toneAmber
class node_historical,node_freshness,node_codec,node_factory,node_tiered,node_memory,node_redisstore,node_caller toneMint
class node_redis,node_proxy,node_psx,node_telemetry toneRose
```

## Components

### HTTP API

- [FastAPI App](https://github.com/psxdata/psxdata-api/blob/main/api/main.py): `api/main.py`
- [Route Registry](https://github.com/psxdata/psxdata-api/blob/main/api/routers/__init__.py): `api/routers/__init__.py`
- [Health Endpoint](https://github.com/psxdata/psxdata-api/blob/main/api/routers/health.py): `api/routers/health.py`
- [Response Models](https://github.com/psxdata/psxdata-api/blob/main/api/schemas.py): `api/schemas.py`

### Market Data

- [Stock Endpoints](https://github.com/psxdata/psxdata-api/blob/main/api/routers/stocks.py): `api/routers/stocks.py`
- [Index Endpoints](https://github.com/psxdata/psxdata-api/blob/main/api/routers/indices.py): `api/routers/indices.py`
- [Sector Endpoints](https://github.com/psxdata/psxdata-api/blob/main/api/routers/sectors.py): `api/routers/sectors.py`
- [Screener Endpoint](https://github.com/psxdata/psxdata-api/blob/main/api/routers/screener.py): `api/routers/screener.py`
- [Market Endpoints](https://github.com/psxdata/psxdata-api/blob/main/api/routers/market.py): `api/routers/market.py`

### Historical Cache

- [History Service](https://github.com/psxdata/psxdata-api/blob/main/api/cache/historical.py): `api/cache/historical.py`
- [Freshness Rules](https://github.com/psxdata/psxdata-api/blob/main/api/cache/freshness.py): `api/cache/freshness.py`
- [Cache Codec](https://github.com/psxdata/psxdata-api/blob/main/api/cache/codec.py): `api/cache/codec.py`
- [Cache Factory](https://github.com/psxdata/psxdata-api/blob/main/api/cache/factory.py): `api/cache/factory.py`
- [Tiered Store](https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py): `api/cache/store.py`
- [Memory LRU](https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py): `api/cache/store.py`
- [Redis Store](https://github.com/psxdata/psxdata-api/blob/main/api/cache/store.py): `api/cache/store.py`

### Integrations

- **Redis Service**
- [Proxy Passthrough](https://github.com/psxdata/psxdata-api/blob/main/api/proxy.py): `api/proxy.py`
- **psxdata SDK**
- [Telemetry](https://github.com/psxdata/psxdata-api/blob/main/api/telemetry.py): `api/telemetry.py`

### Other components

- **API Caller**

## Connections

- API Caller → FastAPI App: sends request (evidence: `README.md`)
- FastAPI App → Route Registry: registers routes (evidence: `api/main.py`)
- Route Registry → Health Endpoint: registers (evidence: `api/routers/__init__.py`)
- Route Registry → Stock Endpoints: registers (evidence: `api/routers/__init__.py`)
- Route Registry → Index Endpoints: registers (evidence: `api/routers/__init__.py`)
- Route Registry → Sector Endpoints: registers (evidence: `api/routers/__init__.py`)
- Route Registry → Screener Endpoint: registers (evidence: `api/routers/__init__.py`)
- Route Registry → Market Endpoints: registers (evidence: `api/routers/__init__.py`)
- Stock Endpoints → Response Models: validates responses (evidence: `api/routers/stocks.py`)
- Index Endpoints → Response Models: validates responses (evidence: `api/routers/indices.py`)
- Sector Endpoints → Response Models: validates responses (evidence: `api/routers/sectors.py`)
- Screener Endpoint → Response Models: validates responses (evidence: `api/routers/screener.py`)
- Market Endpoints → Response Models: validates responses (evidence: `api/routers/market.py`)
- Health Endpoint → Response Models: uses models (evidence: `api/routers/health.py`)
- Stock Endpoints → History Service: gets history (evidence: `api/routers/stocks.py`)
- Stock Endpoints → Proxy Passthrough: uses PSX source (evidence: `api/routers/stocks.py`)
- Index Endpoints → Proxy Passthrough: uses PSX source (evidence: `api/routers/indices.py`)
- Sector Endpoints → Proxy Passthrough: uses PSX source (evidence: `api/routers/sectors.py`)
- Screener Endpoint → Proxy Passthrough: uses PSX source (evidence: `api/routers/screener.py`)
- Market Endpoints → Proxy Passthrough: uses PSX source (evidence: `api/routers/market.py`)
- Proxy Passthrough → psxdata SDK: fetches data (evidence: `api/proxy.py`)
- History Service → psxdata SDK: fetches on miss (evidence: `README.md`)
- History Service → Tiered Store: reads and writes (evidence: `api/cache/historical.py`)
- History Service → Freshness Rules: checks freshness (evidence: `api/cache/historical.py`)
- History Service → Cache Codec: encodes entries (evidence: `api/cache/historical.py`)
- Cache Factory → History Service: builds service (evidence: `api/cache/factory.py`)
- Cache Factory → Tiered Store: constructs store (evidence: `api/cache/factory.py`)
- Cache Factory → Freshness Rules: uses default TTL (evidence: `api/cache/factory.py`)
- FastAPI App → Cache Factory: builds cache (evidence: `api/main.py`)
- FastAPI App → Proxy Passthrough: configures passthrough (evidence: `api/main.py`)
- FastAPI App → Telemetry: flushes telemetry (evidence: `api/main.py`)
- Tiered Store → Memory LRU: checks first (evidence: `api/cache/store.py`)
- Tiered Store → Redis Store: falls back (evidence: `api/cache/store.py`)
- Redis Store → Redis Service: reads and writes (evidence: `api/cache/store.py`)
