Architecture

Architecture

The code is layered so UI gestures cannot become broker mutations by accident.

flowchart TB
    UI[src/ui<br/>PyQt widgets, controllers, workers]
    Web[src/web<br/>authenticated static shell and command API]
    Core[src/core and src/strategy<br/>state, rules, commands, ORB]
    Risk[src/risk<br/>sizing and pre-trade approval]
    Services[src/services<br/>workflows, reconciliation, runtime]
    Infra[src/infrastructure<br/>SQL schemas and repositories]
    API[src/api and src/brokers<br/>KIS protocol adapters]
    Storage[src/utils<br/>configuration, JSON, data loading]

    UI --> Core
    UI --> Services
    Web --> Services
    Services --> Core
    Services --> Risk
    Services --> Infra
    Services --> API
    Infra --> Storage
    API --> Storage

Loading

Entry path

main.py synchronizes the environment schema, loads .env without overriding OS variables, configures logging/Qt handling, creates QApplication, imports MainWindow, and starts the event loop.

Responsibility boundaries

Shared execution/control repositories select PostgreSQL through coordination_engine.py in the current deployment. The private Supabase schema holds all 20 coordination tables; local PC MySQL remains the historical-data cache. Optional public Supabase Auth/Storage projections are a separate feature. The former TiDB source is not a fallback. See Supabase Deployment.

• src/ui: presentation, interaction routing, and background worker lifecycle.
• src/web: authenticated read/command boundary, optimistic browser UX, and non-authoritative live-update invalidations; it never constructs a broker or execution runtime.
• src/core: immutable models, transitions, scanner rules, commands, and execution contracts.
• src/strategy: strategy-neutral contracts and the built-in ORB strategy.
• src/risk: position sizing and final pre-trade decisions.
• src/services: orchestration, persistence, synchronization, leases, reconciliation, journals, and broker workflow boundaries.
• src/infrastructure/database: SQLAlchemy schemas, engines, repositories, refresh, and mirror copy/reconciliation.
• src/api and src/brokers: KIS request/response and broker protocol adapters.

Slow external work normally belongs in QThread or background workers. The remaining chart UI-thread limitation is documented in Performance Audit.

Connected web writes use the same headless domain services, then publish typed coordination pulses. Desktop workers refetch canonical projections, and runtime-state/writability transitions separately trigger board refreshes. See Web/PWA Operator Synchronization.

The active broker path uses immutable ORB order generations: a fresh confirmed breakout submits a passive limit, and a later higher-score generation can be submitted only after the prior zero-fill order is authoritatively cancelled. See Current Order Logic.