# giuse88/duka architecture

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

## Overview

duka is a terminal downloader for Dukascopy historical Forex and related market data. A user supplies symbols, dates, and output options; the CLI validates them and hands the request to an application coordinator, which schedules per-symbol/day work, fetches hourly feed data, decodes it into ticks, optionally aggregates candles, and writes CSV files. The README also highlights concurrent downloads, multiple symbols, and progress estimates. Source excerpts show the fetch, processing, and output implementations; relationships to unsampled code are omitted.

Main entry points: [`duka/app/app.py`](https://github.com/giuse88/duka/blob/master/duka/app/app.py) (Download coordinator), [`duka/main.py`](https://github.com/giuse88/duka/blob/master/duka/main.py) (CLI entry), [`duka/core/csv_dumper.py`](https://github.com/giuse88/duka/blob/master/duka/core/csv_dumper.py) (CSV dumper), [`duka/core/fetch.py`](https://github.com/giuse88/duka/blob/master/duka/core/fetch.py) (Hourly fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and coordination"]
  node_main["CLI entry<br/>[main.py]"]
  node_utils["Date and options<br/>[utils.py]"]
  node_app["Download coordinator<br/>[app.py]"]
  node_progress["Progress estimates<br/>[app.py]"]
end

subgraph group_download["Download and decoding"]
  node_fetch["Hourly fetch<br/>[fetch.py]"]
  node_decode["Decode and normalize<br/>[processor.py]"]
end

subgraph group_format["Market data formatting"]
  node_tickdata["Normalized ticks<br/>[processor.py]"]
  node_candle["Candle aggregation<br/>[csv_dumper.py]"]
  node_candlemodel["Candle values<br/>[candle.py]"]
end

subgraph group_output["CSV output"]
  node_csvdumper["CSV dumper<br/>[csv_dumper.py]"]
end

node_user(("Terminal user"))
node_feed["Dukascopy feed"]
node_filesystem[("Output folder")]

node_user -->|"supplies options"| node_main
node_main -->|"validates dates"| node_utils
node_main -->|"validates timeframe"| node_utils
node_main -->|"starts download"| node_app
node_app -->|"fetches each day"| node_fetch
node_fetch -->|"requests hourly data"| node_feed
node_app -->|"decodes response"| node_decode
node_decode -->|"produces ticks"| node_tickdata
node_app -->|"appends day data"| node_csvdumper
node_csvdumper -->|"aggregates timeframe"| node_candle
node_candle -->|"creates candles"| node_candlemodel
node_csvdumper -->|"writes CSV"| node_filesystem
node_app -->|"updates estimates"| node_progress

click node_main "https://github.com/giuse88/duka/blob/master/duka/main.py"
click node_utils "https://github.com/giuse88/duka/blob/master/duka/core/utils.py"
click node_app "https://github.com/giuse88/duka/blob/master/duka/app/app.py"
click node_progress "https://github.com/giuse88/duka/blob/master/duka/app/app.py"
click node_fetch "https://github.com/giuse88/duka/blob/master/duka/core/fetch.py"
click node_decode "https://github.com/giuse88/duka/blob/master/duka/core/processor.py"
click node_tickdata "https://github.com/giuse88/duka/blob/master/duka/core/processor.py"
click node_csvdumper "https://github.com/giuse88/duka/blob/master/duka/core/csv_dumper.py"
click node_candle "https://github.com/giuse88/duka/blob/master/duka/core/csv_dumper.py"
click node_candlemodel "https://github.com/giuse88/duka/blob/master/duka/core/candle.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_main,node_utils,node_app,node_progress,node_user toneBlue
class node_fetch,node_decode,node_filesystem toneAmber
class node_tickdata,node_candle,node_candlemodel toneMint
class node_csvdumper toneRose
class node_feed toneIndigo
```

## Components

### CLI and coordination

- [CLI entry](https://github.com/giuse88/duka/blob/master/duka/main.py): `duka/main.py`
- [Date and options](https://github.com/giuse88/duka/blob/master/duka/core/utils.py): `duka/core/utils.py`
- [Download coordinator](https://github.com/giuse88/duka/blob/master/duka/app/app.py): `duka/app/app.py`
- [Progress estimates](https://github.com/giuse88/duka/blob/master/duka/app/app.py): `duka/app/app.py`

### Download and decoding

- [Hourly fetch](https://github.com/giuse88/duka/blob/master/duka/core/fetch.py): `duka/core/fetch.py`
- [Decode and normalize](https://github.com/giuse88/duka/blob/master/duka/core/processor.py): `duka/core/processor.py`

### Market data formatting

- [Normalized ticks](https://github.com/giuse88/duka/blob/master/duka/core/processor.py): `duka/core/processor.py`
- [Candle aggregation](https://github.com/giuse88/duka/blob/master/duka/core/csv_dumper.py): `duka/core/csv_dumper.py`
- [Candle values](https://github.com/giuse88/duka/blob/master/duka/core/candle.py): `duka/core/candle.py`

### CSV output

- [CSV dumper](https://github.com/giuse88/duka/blob/master/duka/core/csv_dumper.py): `duka/core/csv_dumper.py`

### Other components

- **Terminal user**
- **Dukascopy feed**
- **Output folder**

## Connections

- Terminal user → CLI entry: supplies options
- CLI entry → Date and options: validates dates
- CLI entry → Date and options: validates timeframe
- CLI entry → Download coordinator: starts download
- Download coordinator → Hourly fetch: fetches each day
- Hourly fetch → Dukascopy feed: requests hourly data
- Download coordinator → Decode and normalize: decodes response
- Decode and normalize → Normalized ticks: produces ticks
- Download coordinator → CSV dumper: appends day data
- CSV dumper → Candle aggregation: aggregates timeframe
- Candle aggregation → Candle values: creates candles
- CSV dumper → Output folder: writes CSV
- Download coordinator → Progress estimates: updates estimates