# jjrune/mykiwoom architecture

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

- Interactive diagram: https://gitdiagram.com/jjrune/mykiwoom
- Repository: https://github.com/jjrune/mykiwoom

## Overview

1. **Repository purpose**
   - This is a Windows-only, Python-based automated trading system for Kiwoom Securities.
   - It is not a single app, but a set of coordinated executables/scripts for **login, live trading, market-data collection, backtesting, and daily DB maintenance**.

2. **Top-level execution model**
   - The system is driven by `.bat` launchers, which are intended to be scheduled by Windows Task Scheduler.
   - Typical startup flow is: **version update → auto-login → trader app**.
   - Separate batch files also run **day-data download**, **tick updates**, and **multiple backtest modes**.

3. **Core runtime boundary: `trader/`**
   - `trader/` is the main live trading application and UI.
   - It contains:
     - `window.py` for the main PyQt desktop UI,
     - `worker.py` for background processing,
     - `query.py` for Kiwoom/OpenAPI requests,
     - `strategy_*.py` for short/mid/long/tick trading logic,
     - `updater_chart.py` and `updater_hoga.py` for chart and order-book refresh,
     - `telegrammsg.py` and `sound.py` for external notifications.
   - This folder is the central integration point between **market data, strategies, order execution, and user-facing controls**.

4. **Live trading data flow**
   - The trader app logs into Kiwoom, initializes required DB tables, and registers market/sector/event subscriptions.
   - Real-time data then feeds into strategy modules.
   - Strategy decisions trigger order actions through the Kiwoom request layer.
   - Trade events, charts, and order-book state are reflected back into the UI.
   - Notifications are sent through Telegram and sound alerts.

5. **Strategy partitioning**
   - Strategies are split by timeframe:
     - `strategy_short.py`
     - `strategy_mid.py`
     - `strategy_long.py`
     - `strategy_tick.py`
   - The live system can operate with different timing horizons, while the tick strategy handles very short-term behavior.
   - The README indicates that some buy/sell strategy internals are intentionally private, so the visible architecture is modular even if the decision logic is partially hidden.

6. **Market data collection: `tick/`**
   - `tick/` focuses on second-level tick capture and analysis.
   - `updater_tick.py`, `worker.py`, and `window.py` support collecting and managing tick data.
   - `backtester_tick.py`, `backtester_tickm.py`, and `backfinder_tick.py` operate on stored tick history.
   - The `tick/graph/` directory suggests result visualization artifacts are generated and stored locally.

7. **Historical/day-level analysis: `day/`**
   - `day/` contains daily-bar workflow for short, mid, and long strategies.
   - `download_daydata.py` fetches day-level historical data.
   - `updater_short.py`, `updater_mid.py`, `updater_long.py` update the local DB after market close.
   - `backtester_short.py`, `backtester_mid.py`, `backtester_long.py` evaluate strategies against historical day data.
   - This folder is the offline research/maintenance side of the system, distinct from live execution.

8. **Database as shared state**
   - `db/stg.db` is the central persistent store.
   - It appears to hold:
     - historical tick/day data,
     - backtest results,
     - trade history,
     - UI/reporting data,
     - possibly watchlists and strategy state.
   - The repo is architected so both live trading and offline backtesting use the same local SQLite database as the source of truth.

9. **Login and environment preparation: `login/`**
   - `login/` contains account automation and version management:
     - `autologin1.py`, `autologin2.py` for two accounts,
     - `manuallogin.py` for fallback manual login,
     - `versionupdater.py` for Kiwoom client/version synchronization.
   - `login/user.txt` stores account configuration.
   - This is a separate pre-trading boundary: the trading system depends on the brokerage client being authenticated and up to date before live modules can function.

10. **Common configuration and utilities: `utility/`**
    - `utility/setting.py` holds paths, UI colors, fonts, and environment-specific configuration.
    - `utility/static.py` provides shared helper functions/constants.
    - This folder is the repo’s configuration spine and is expected to be edited when relocating the installation or changing the UI theme.

11. **External integrations**
    - **Kiwoom Securities OpenAPI / HTS** is the primary external trading and market-data source.
    - **Telegram** is used for operational notifications.
    - **Local audio** is used for alerts.
    - The README also mentions HTS condition-search formulas, which are part of the external trading platform setup and feed the live trader.

12. **UI and operator controls**
    - The main UI is a large PyQt desktop application optimized for a specific screen resolution.
    - It provides charts, order-book panels, trade history, profit summaries, and system controls.
    - There are explicit modes for:
      - **test mode**: manual command-by-command execution,
      - **simulated trading**: live server connection without real orders,
      - **live trading**: actual order transmission.
    - This makes the UI not just a dashboard, but an operational control surface.

13. **Batch/script orchestration as infrastructure**
    - The `.bat` files are part of the architecture, not just launch shortcuts.
    - They define how the system is sequenced across boot, login, updater, trader, and backtest workflows.
    - Some batch files are intended for unattended operation and others are used for debugging with `pause`, which suggests the repo is designed for both scheduled execution and manual validation.

14. **Operational artifacts**
    - `log/` stores runtime logs.
    - `icon/` contains UI assets used by the desktop application.
    - These are supporting assets rather than core logic, but they reinforce that this is a local desktop trading workstation with persistent operational history.

15. **Diagram takeaway**
    - If you draw the architecture, the clearest layout is:
      - **Scheduler / batch scripts** at the top,
      - branching into **login/version control**, **live trader UI**, **tick/day data pipelines**, and **backtest engines**,
      - all converging on a shared **SQLite DB**,
      - with external connections to **Kiwoom OpenAPI/HTS** and **Telegram**.

Main entry points: [`db/stg.db`](https://github.com/jjrune/mykiwoom/blob/master/db/stg.db) (SQLite DB), [`trader/worker.py`](https://github.com/jjrune/mykiwoom/blob/master/trader/worker.py) (Trader worker), [`trader/window.py`](https://github.com/jjrune/mykiwoom/blob/master/trader/window.py) (Trader UI), [`trader/query.py`](https://github.com/jjrune/mykiwoom/blob/master/trader/query.py) (Kiwoom query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_orchestration["Orchestration"]
  node_node_batch_launchers["Batch launchers<br/>Windows batch"]
end

subgraph group_grp_login["Login"]
  node_node_login_version["Version updater<br/>broker prep<br/>[versionupdater.py]"]
  node_node_login_auto1["Auto login 1<br/>account login<br/>[autologin1.py]"]
  node_node_login_auto2["Auto login 2<br/>account login<br/>[autologin2.py]"]
  node_node_login_manual["Manual login<br/>fallback login<br/>[manuallogin.py]"]
end

subgraph group_grp_trader["Live trader"]
  node_node_trader_window["Trader UI<br/>PyQt desktop<br/>[window.py]"]
  node_node_trader_worker["Trader worker<br/>runtime worker<br/>[worker.py]"]
  node_node_trader_query["Kiwoom query<br/>api adapter<br/>[query.py]"]
  node_node_trader_strategies{{"Strategies<br/>timeframe logic"}}
  node_node_trader_updaters["Chart/Hoga updaters<br/>market refresh"]
  node_node_trader_notify["Alerts<br/>notifications"]
end

subgraph group_grp_tick["Tick pipeline"]
  node_node_tick_window["Tick window<br/>PyQt desktop<br/>[window.py]"]
  node_node_tick_worker["Tick worker<br/>pipeline worker<br/>[worker.py]"]
  node_node_tick_update["Tick updater<br/>tick capture<br/>[updater_tick.py]"]
  node_node_tick_backtests["Tick backtests<br/>research engine"]
end

subgraph group_grp_day["Day pipeline"]
  node_node_day_download["Day download<br/>historical fetch"]
  node_node_day_updaters["Day updaters<br/>close-of-day update"]
  node_node_day_backtests["Day backtests<br/>research engine"]
end

subgraph group_grp_shared["Shared state"]
  node_node_db[("SQLite DB<br/>persistent store<br/>[stg.db]")]
  node_node_settings["Settings<br/>config spine<br/>[setting.py]"]
  node_node_static["Static utils<br/>shared helpers<br/>[static.py]"]
end

node_node_kiwoom(("Kiwoom OpenAPI<br/>external broker"))
node_node_telegram(("Telegram<br/>external alerts"))
node_node_audio(("Audio alerts<br/>local output"))

node_node_batch_launchers -->|"start"| node_node_login_version
node_node_batch_launchers -->|"start"| node_node_login_auto1
node_node_batch_launchers -->|"start"| node_node_login_auto2
node_node_login_auto1 -->|"authenticate"| node_node_kiwoom
node_node_login_auto2 -->|"authenticate"| node_node_kiwoom
node_node_login_manual -->|"authenticate"| node_node_kiwoom
node_node_batch_launchers -->|"start"| node_node_trader_window
node_node_trader_window -->|"orchestrates"| node_node_trader_worker
node_node_trader_worker -->|"orders/data"| node_node_trader_query
node_node_trader_worker -->|"feeds"| node_node_trader_strategies
node_node_trader_strategies -->|"signal orders"| node_node_trader_query
node_node_trader_worker -->|"refreshes"| node_node_trader_updaters
node_node_trader_worker -->|"alerts"| node_node_trader_notify
node_node_trader_updaters -->|"render"| node_node_trader_window
node_node_trader_query -->|"API calls"| node_node_kiwoom
node_node_trader_window -->|"reads/writes"| node_node_db
node_node_tick_window -->|"orchestrates"| node_node_tick_worker
node_node_tick_worker -->|"captures"| node_node_tick_update
node_node_tick_update -->|"stores"| node_node_db
node_node_tick_backtests -->|"reads"| node_node_db
node_node_day_download -->|"fetches"| node_node_kiwoom
node_node_day_download -->|"stores"| node_node_db
node_node_day_updaters -->|"updates"| node_node_db
node_node_day_backtests -->|"reads"| node_node_db
node_node_trader_window -->|"configures"| node_node_settings
node_node_tick_window -->|"configures"| node_node_settings
node_node_day_updaters -->|"helpers"| node_node_static
node_node_trader_notify -->|"sends"| node_node_telegram
node_node_trader_notify -->|"plays"| node_node_audio

click node_node_login_version "https://github.com/jjrune/mykiwoom/blob/master/login/versionupdater.py"
click node_node_login_auto1 "https://github.com/jjrune/mykiwoom/blob/master/login/autologin1.py"
click node_node_login_auto2 "https://github.com/jjrune/mykiwoom/blob/master/login/autologin2.py"
click node_node_login_manual "https://github.com/jjrune/mykiwoom/blob/master/login/manuallogin.py"
click node_node_trader_window "https://github.com/jjrune/mykiwoom/blob/master/trader/window.py"
click node_node_trader_worker "https://github.com/jjrune/mykiwoom/blob/master/trader/worker.py"
click node_node_trader_query "https://github.com/jjrune/mykiwoom/blob/master/trader/query.py"
click node_node_tick_window "https://github.com/jjrune/mykiwoom/blob/master/tick/window.py"
click node_node_tick_worker "https://github.com/jjrune/mykiwoom/blob/master/tick/worker.py"
click node_node_tick_update "https://github.com/jjrune/mykiwoom/blob/master/tick/updater_tick.py"
click node_node_day_download "https://github.com/jjrune/mykiwoom/blob/master/day/download_daydata.py"
click node_node_db "https://github.com/jjrune/mykiwoom/blob/master/db/stg.db"
click node_node_settings "https://github.com/jjrune/mykiwoom/blob/master/utility/setting.py"
click node_node_static "https://github.com/jjrune/mykiwoom/blob/master/utility/static.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_node_batch_launchers toneBlue
class node_node_login_version,node_node_login_auto1,node_node_login_auto2,node_node_login_manual toneAmber
class node_node_trader_window,node_node_trader_worker,node_node_trader_query,node_node_trader_strategies,node_node_trader_updaters,node_node_trader_notify toneMint
class node_node_tick_window,node_node_tick_worker,node_node_tick_update,node_node_tick_backtests toneRose
class node_node_day_download,node_node_day_updaters,node_node_day_backtests toneIndigo
class node_node_db,node_node_settings,node_node_static toneTeal
class node_node_kiwoom,node_node_telegram,node_node_audio toneNeutral
```

## Components

### Orchestration

Windows batch launchers that sequence login, updates, trading, and backtests.

- **Batch launchers**: Windows batch · Scheduled entrypoints that start update, login, trader, and research workflows.

### Login

Account automation and broker client version management.

- [Version updater](https://github.com/jjrune/mykiwoom/blob/master/login/versionupdater.py): broker prep · Synchronizes the Kiwoom client/version before trading. · `login/versionupdater.py`
- [Auto login 1](https://github.com/jjrune/mykiwoom/blob/master/login/autologin1.py): account login · Automated login flow for the first account. · `login/autologin1.py`
- [Auto login 2](https://github.com/jjrune/mykiwoom/blob/master/login/autologin2.py): account login · Automated login flow for the second account. · `login/autologin2.py`
- [Manual login](https://github.com/jjrune/mykiwoom/blob/master/login/manuallogin.py): fallback login · Manual fallback login path when automation is not used. · `login/manuallogin.py`

### Live trader

Main live trading application, UI, execution, and notifications.

- [Trader UI](https://github.com/jjrune/mykiwoom/blob/master/trader/window.py): PyQt desktop · Main operator console for live trading, charts, and controls. · `trader/window.py`
- [Trader worker](https://github.com/jjrune/mykiwoom/blob/master/trader/worker.py): runtime worker · Background processing and orchestration for live trading tasks. · `trader/worker.py`
- [Kiwoom query](https://github.com/jjrune/mykiwoom/blob/master/trader/query.py): api adapter · Request layer for Kiwoom/OpenAPI calls and order actions. · `trader/query.py`
- **Strategies**: timeframe logic · Short, mid, long, and tick trading logic modules.
- **Chart/Hoga updaters**: market refresh · Chart and order-book refresh components for the live UI.
- **Alerts**: notifications · Telegram messages and local sound alerts.

### Tick pipeline

Second-level tick capture, management, and tick backtesting.

- [Tick window](https://github.com/jjrune/mykiwoom/blob/master/tick/window.py): PyQt desktop · Tick-data management UI. · `tick/window.py`
- [Tick worker](https://github.com/jjrune/mykiwoom/blob/master/tick/worker.py): pipeline worker · Background tick capture and processing runtime. · `tick/worker.py`
- [Tick updater](https://github.com/jjrune/mykiwoom/blob/master/tick/updater_tick.py): tick capture · Second-level tick collection and local update flow. · `tick/updater_tick.py`
- **Tick backtests**: research engine · Tick backtester and backfinder modes over stored history.

### Day pipeline

Daily-bar downloads, maintenance, and backtesting.

- [Day download](https://github.com/jjrune/mykiwoom/blob/master/day/download_daydata.py): historical fetch · Downloads day-level historical data from Kiwoom. · `day/download_daydata.py`
- **Day updaters**: close-of-day update · Short, mid, and long daily DB maintenance after market close.
- **Day backtests**: research engine · Short, mid, and long strategy backtesting on daily bars.

### Shared state

Common database, configuration, and assets used across workflows.

- [SQLite DB](https://github.com/jjrune/mykiwoom/blob/master/db/stg.db): persistent store · Shared local database for market data, trades, results, and UI state. · `db/stg.db`
- [Settings](https://github.com/jjrune/mykiwoom/blob/master/utility/setting.py): config spine · Shared paths, UI settings, and environment configuration. · `utility/setting.py`
- [Static utils](https://github.com/jjrune/mykiwoom/blob/master/utility/static.py): shared helpers · Common constants and helper functions used across modules. · `utility/static.py`

### Other components

- **Kiwoom OpenAPI**: external broker · Primary brokerage and market-data integration boundary.
- **Telegram**: external alerts · Out-of-band operational notifications from the trading system.
- **Audio alerts**: local output · Sound-based operator alerts on the local workstation.

## Connections

- Batch launchers → Version updater: start · Launchers sequence version sync before authenticated use.
- Batch launchers → Auto login 1: start · Scheduled login path for account 1.
- Batch launchers → Auto login 2: start · Scheduled login path for account 2.
- Auto login 1 → Kiwoom OpenAPI: authenticate · Logs into the brokerage client.
- Auto login 2 → Kiwoom OpenAPI: authenticate · Logs into the brokerage client.
- Manual login → Kiwoom OpenAPI: authenticate · Fallback manual brokerage login.
- Batch launchers → Trader UI: start · Opens the live trading application.
- Trader UI → Trader worker: orchestrates · UI delegates background work and state coordination.
- Trader worker → Kiwoom query: orders/data · Executes OpenAPI requests and order transmission.
- Trader worker → Strategies: feeds · Routes live market data into strategy modules.
- Strategies → Kiwoom query: signal orders · Strategy decisions are converted into broker actions.
- Trader worker → Chart/Hoga updaters: refreshes · Updates charts and order-book views.
- Trader worker → Alerts: alerts · Emits operational notifications.
- Chart/Hoga updaters → Trader UI: render · Feeds live UI panels with chart and hoga state.
- Kiwoom query → Kiwoom OpenAPI: API calls · Uses Kiwoom/OpenAPI as the execution and market-data boundary.
- Trader UI → SQLite DB: reads/writes · Persists and displays trading state and history.
- Tick window → Tick worker: orchestrates · Tick UI controls the background tick pipeline.
- Tick worker → Tick updater: captures · Maintains second-level tick data.
- Tick updater → SQLite DB: stores · Writes tick history to the shared database.
- Tick backtests → SQLite DB: reads · Backtesting consumes stored tick history and results.
- Day download → Kiwoom OpenAPI: fetches · Downloads daily historical data from the brokerage platform.
- Day download → SQLite DB: stores · Persists downloaded day data locally.
- Day updaters → SQLite DB: updates · Refreshes day-level DB tables after market close.
- Day backtests → SQLite DB: reads · Evaluates strategies against historical day data.
- Trader UI → Settings: configures · Uses shared paths, colors, and runtime settings.
- Tick window → Settings: configures · Uses shared settings for the tick tools.
- Day updaters → Static utils: helpers · Reuses shared utility functions and constants.
- Alerts → Telegram: sends · Operational messages are sent to Telegram.
- Alerts → Audio alerts: plays · Local sound alerts for trading events.