# visikai/ohlc-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/visikai/ohlc-toolkit
- Repository: https://github.com/visikai/ohlc-toolkit

## Overview

OHLC Toolkit is a Polars-native library for fetching, reading, validating, and transforming market-data frames. Its documented workflow fetches a release and verifies its assets, reads and checks the resulting frame, aggregates it into windows, then adds returns; quality policy is a separate follow-up step. The package also exposes schedules and phased indicators as distinct capabilities. The README and sampled source support the main workflow links; unsampled subsystem internals are represented at their exact enclosing directories, without implying unverified wiring.

Main entry points: [`src/ohlc_toolkit/source/reader.py`](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/reader.py) (Read source), [`src/ohlc_toolkit/snapshot/fetcher.py`](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/fetcher.py) (Fetch snapshot), [`src/ohlc_toolkit/snapshot/continuity.py`](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/continuity.py) (Read snapshot frame), [`src/ohlc_toolkit/windows/engine.py`](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/engine.py) (Compute windows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_snapshot["Snapshot access"]
  node_snapshot_fetch["Fetch snapshot<br/>[fetcher.py]"]
  node_snapshot_read["Read snapshot frame<br/>[continuity.py]"]
  node_continuity["Verify continuity<br/>[continuity.py]"]
end

subgraph group_frames["Frame processing"]
  node_source_reader["Read source<br/>[reader.py]"]
  node_source_validation["Validate source<br/>[validation.py]"]
  node_source_profile["Source profiles<br/>[profile.py]"]
  node_window_engine["Compute windows<br/>[engine.py]"]
  node_window_reference["Window reference<br/>[reference.py]"]
  node_window_quality["Quality policy<br/>[quality.py]"]
  node_window_resolution["Window resolution<br/>[resolution.py]"]
end

subgraph group_analytics["Analytics"]
  node_returns["Returns and excursions<br/>[primitives.py]"]
  node_return_alignment["Return alignment<br/>[alignment.py]"]
  node_indicators["Phased indicators"]
  node_indicator_frames["Indicator frame checks<br/>[frames.py]"]
end

subgraph group_planning["Schedules"]
  node_schedule_generators["Window schedules<br/>[generators.py]"]
  node_schedule_cadence["Emit cadence rules<br/>[cadence.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_temporal["Durations and calendar"]
  node_logging["Logging and errors"]
end

node_user(("Toolkit caller"))
node_release["Published release"]

node_user -->|"requests fetch"| node_snapshot_fetch
node_release -->|"provides assets"| node_snapshot_fetch
node_snapshot_fetch -->|"verified result"| node_snapshot_read
node_snapshot_read -->|"reads frame"| node_source_reader
node_user -->|"reads source"| node_source_reader
node_source_reader -->|"validates frame"| node_source_validation
node_source_reader -->|"uses profile"| node_source_profile
node_user -->|"aggregates frame"| node_window_engine
node_window_engine -->|"window frame"| node_window_quality
node_user -->|"adds returns"| node_returns
node_returns -->|"resolves counterparts"| node_return_alignment
node_user -->|"checks continuity"| node_continuity
node_user -->|"generates schedule"| node_schedule_generators
node_user -->|"resolves cadence"| node_schedule_cadence
node_user -->|"computes indicators"| node_indicators
node_indicators -->|"checks frame"| node_indicator_frames
node_user -->|"uses oracle"| node_window_reference
node_user -->|"resolves windows"| node_window_resolution

click node_snapshot_fetch "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/fetcher.py"
click node_snapshot_read "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/continuity.py"
click node_continuity "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/continuity.py"
click node_source_reader "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/reader.py"
click node_source_validation "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/validation.py"
click node_source_profile "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/profile.py"
click node_window_engine "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/engine.py"
click node_window_reference "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/reference.py"
click node_window_quality "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/quality.py"
click node_window_resolution "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/resolution.py"
click node_returns "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/returns/primitives.py"
click node_return_alignment "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/returns/alignment.py"
click node_indicators "https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/indicators"
click node_indicator_frames "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/indicators/frames.py"
click node_schedule_generators "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/schedules/generators.py"
click node_schedule_cadence "https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/schedules/cadence.py"
click node_temporal "https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/temporal"
click node_logging "https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/config"

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_snapshot_fetch,node_snapshot_read,node_continuity toneBlue
class node_source_reader,node_source_validation,node_source_profile,node_window_engine,node_window_reference,node_window_quality,node_window_resolution toneAmber
class node_returns,node_return_alignment,node_indicators,node_indicator_frames toneMint
class node_schedule_generators,node_schedule_cadence toneRose
class node_temporal,node_logging,node_user,node_release toneIndigo
```

## Components

### Snapshot access

- [Fetch snapshot](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/fetcher.py): `src/ohlc_toolkit/snapshot/fetcher.py`
- [Read snapshot frame](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/continuity.py): `src/ohlc_toolkit/snapshot/continuity.py`
- [Verify continuity](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/snapshot/continuity.py): `src/ohlc_toolkit/snapshot/continuity.py`

### Frame processing

- [Read source](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/reader.py): `src/ohlc_toolkit/source/reader.py`
- [Validate source](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/validation.py): `src/ohlc_toolkit/source/validation.py`
- [Source profiles](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/source/profile.py): `src/ohlc_toolkit/source/profile.py`
- [Compute windows](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/engine.py): `src/ohlc_toolkit/windows/engine.py`
- [Window reference](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/reference.py): `src/ohlc_toolkit/windows/reference.py`
- [Quality policy](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/quality.py): `src/ohlc_toolkit/windows/quality.py`
- [Window resolution](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/windows/resolution.py): `src/ohlc_toolkit/windows/resolution.py`

### Analytics

- [Returns and excursions](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/returns/primitives.py): `src/ohlc_toolkit/returns/primitives.py`
- [Return alignment](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/returns/alignment.py): `src/ohlc_toolkit/returns/alignment.py`
- [Phased indicators](https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/indicators): `src/ohlc_toolkit/indicators`
- [Indicator frame checks](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/indicators/frames.py): `src/ohlc_toolkit/indicators/frames.py`

### Schedules

- [Window schedules](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/schedules/generators.py): `src/ohlc_toolkit/schedules/generators.py`
- [Emit cadence rules](https://github.com/visikai/ohlc-toolkit/blob/main/src/ohlc_toolkit/schedules/cadence.py): `src/ohlc_toolkit/schedules/cadence.py`

### Shared foundations

- [Durations and calendar](https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/temporal): `src/ohlc_toolkit/temporal`
- [Logging and errors](https://github.com/visikai/ohlc-toolkit/tree/main/src/ohlc_toolkit/config): `src/ohlc_toolkit/config`

### Other components

- **Toolkit caller**
- **Published release**

## Connections

- Toolkit caller → Fetch snapshot: requests fetch
- Published release → Fetch snapshot: provides assets
- Fetch snapshot → Read snapshot frame: verified result
- Read snapshot frame → Read source: reads frame
- Toolkit caller → Read source: reads source
- Read source → Validate source: validates frame
- Read source → Source profiles: uses profile
- Toolkit caller → Compute windows: aggregates frame
- Compute windows → Quality policy: window frame
- Toolkit caller → Returns and excursions: adds returns
- Returns and excursions → Return alignment: resolves counterparts
- Toolkit caller → Verify continuity: checks continuity
- Toolkit caller → Window schedules: generates schedule
- Toolkit caller → Emit cadence rules: resolves cadence
- Toolkit caller → Phased indicators: computes indicators
- Phased indicators → Indicator frame checks: checks frame
- Toolkit caller → Window reference: uses oracle
- Toolkit caller → Window resolution: resolves windows