# mattsta/icli architecture

> Architecture diagram of the GitHub repository mattsta/icli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mattsta/icli
- Repository: https://github.com/mattsta/icli

## Overview

##### Project Type and Purpose
- `icli` is an open‑source, full-featured Command‑Line Interface (CLI) tool for live and paper trading via Interactive Brokers (IBKR).
- Purpose: rapid entry of orders, real‑time streaming quotes, account management, and optional audio notifications.

##### File Structure
- Top‐level:
- `icli/` – main package
- `pyproject.toml` – build and dependency config (Poetry)
- README, LICENSE, .gitignore
- Inside `icli/`:
- `__main__.py` – entry point, sets up event loop & env
- `cli.py` – REPL loop using prompt‑toolkit, command dispatcher
- `lang.py` – implementations of each CLI command via a dispatch framework
- `awwdio.py` – optional audio announcement client integration
- `futsexchanges.py` – futures symbol ↔ exchange mapping generator
- `helpers.py` – contracts and naming utilities
- `orders.py` – IBKR Order object builders and metadata handling
- `calc.py`, `tinyalgo.py` – calculator and experimental algo hooks

##### README for Insights
- Entry point and architecture summary at the bottom (“Architecture” section).
- External dependencies: IBKR Gateway/TWS, `ib_insync` wrapper, optional `awwdio` audio server.
- Persistence: `~/.tplatcli_ibkr_history.*`, timestamped `icli-*.log`.

##### Main Components
a. Frontend:
– Terminal / User
– `prompt_toolkit` REPL
b. Core CLI Application:
– `__main__.py`: bootstrap, read ENV, start event loop
– `cli.py`: `IBKRCmdlineApp.dorepl()` — prompt loop & parser
– Command Dispatcher (`mutil/dispatch.py`‑based)
– Command Implementations in `lang.py`, `calc.py`, `tinyalgo.py`
– Helpers (`helpers.py`, `orders.py`, `futsexchanges.py`)
c. External Services:
– IBKR Gateway/TWS (local host + port)
– IBKR upstream trade/data API
– Optional `awwdio` audio notification server
d. Persistence & Logging:
– History file in user home `~/.tplatcli_ibkr_history.{live,sandbox}`
– Log file `icli-{timestamp}.log`
– Environment variables / `.env.icli`

##### Relationships and Data Flows
- User types commands in Terminal → REPL (cli.py) → Dispatcher (mutil) → Command classes (lang.py, etc.)
- Commands that request market data or send orders call `ib_insync` wrapper → IBKR Gateway → IBKR servers.
- Command results (quotes, positions, logs) streamed back to CLI UI.
- Execution events optionally sent to `awwdio` for speech.
- All API calls and events appended to a logfile; user inputs persisted to history file.

##### Architectural Patterns & Design Principles
- Modular command classes (Command pattern via dispatch map in `lang.py`).
- Separation of concerns:
- REPL / I/O (cli.py)
- Business logic (lang.py, calc.py, tinyalgo.py)
- External integrations (awwdio.py, futsexchanges.py, orders.py)
- Event-driven loop (prompt-toolkit) for concurrency & async IO (IBKR streaming).
- Environment-based configuration (12‑factor style via ENV vars / `.env.icli`).

##### Relevant Technologies & Libraries
- Python 3.x, Poetry (`pyproject.toml`)
- prompt‑toolkit for interactive CLI
- ib_insync for IBKR API wrapper
- questionary for prompts
- `mutil/dispatch.py` for command dispatching
- Standard logging module
- Optional HTTP client to `awwdio`

- Use clear, descriptive labels for each component (e.g., “REPL Loop”, “Order Builder”, “IBKR Gateway”).
- User → REPL
- REPL → Dispatcher → Command Classes
- Commands → IBKR API → IBKR Gateway → IBKR Servers
- Commands → Log Writer / History Persister
- Optional Commands → AWwdio → Audio Output
- Blue for CLI core
- Green for external services
- Orange for helpers & utilities
- Gray for persistence & config
- Clouds for external services (IBKR, AWwdio)

## Diagram (Mermaid)

```mermaid
graph TD
    U["Terminal / User"]:::frontend
    U -->|types commands| REPL["REPL Loop (cli.py)"]:::core

    subgraph "CLI Core"
        EP["Entry Point (__main__.py)"]:::core
        REPL --> EP
        EP --> DP["Dispatcher (lang.py)"]:::core

        subgraph "Commands"
            C1["Core Commands (lang.py)"]:::core
            C2["Calculator Commands (calc.py)"]:::core
            C3["Experimental Algo Hooks (tinyalgo.py)"]:::core
        end
        DP --> C1
        DP --> C2
        DP --> C3

        subgraph "Utilities"
            H["Contract & Naming Utilities (helpers.py)"]:::util
            O["Order Builders & Metadata (orders.py)"]:::util
            F["Futures Mapping Generator (futsexchanges.py)"]:::util
        end
        C1 --> H
        C1 --> O
        C1 --> F

        subgraph "Audio Notifications"
            A["AWwdio Client (awwdio.py)"]:::ext
        end
        C1 -->|optional audio events| A
    end

    C1 -->|calls ib_insync wrapper| IBCli["IB_insync Wrapper"]:::util
    IBCli -->|connects to| Gateway["IBKR Gateway/TWS"]:::ext
    Gateway -->|streams data to| IBCli
    Gateway -->|forwards to| IBServ["IBKR Servers"]:::ext

    C1 -->|writes history| Hist["History File (~/.tplatcli_ibkr_history)"]:::storage
    C1 -->|appends logs| Logf["Log File (icli-*.log)"]:::storage

    EP -->|loads config| Env[".env.icli / ENV Vars"]:::config
    ConfigFile["pyproject.toml"]:::config
    RD["README.md"]:::config
    LIC["LICENSE"]:::config
    ConfigFile --> EP
    RD --> U
    LIC --> U

    click EP "https://github.com/mattsta/icli/blob/main/icli/__main__.py"
    click REPL "https://github.com/mattsta/icli/blob/main/icli/cli.py"
    click DP "https://github.com/mattsta/icli/blob/main/icli/lang.py"
    click C1 "https://github.com/mattsta/icli/blob/main/icli/lang.py"
    click C2 "https://github.com/mattsta/icli/blob/main/icli/calc.py"
    click C3 "https://github.com/mattsta/icli/blob/main/icli/tinyalgo.py"
    click H "https://github.com/mattsta/icli/blob/main/icli/helpers.py"
    click O "https://github.com/mattsta/icli/blob/main/icli/orders.py"
    click F "https://github.com/mattsta/icli/blob/main/icli/futsexchanges.py"
    click A "https://github.com/mattsta/icli/blob/main/icli/awwdio.py"
    click ConfigFile "https://github.com/mattsta/icli/blob/main/pyproject.toml"
    click RD "https://github.com/mattsta/icli/blob/main/README.md"
    click LIC "https://github.com/mattsta/icli/tree/main/LICENSE"

    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ext fill:#d4edda,stroke:#333,stroke-width:1px
    classDef util fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef config fill:#f8d7da,stroke:#333,stroke-width:1px
```
