# dteam-top/tsw-cli architecture

> Architecture diagram of the GitHub repository dteam-top/tsw-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dteam-top/tsw-cli
- Repository: https://github.com/dteam-top/tsw-cli

## Overview

##### Project type and purpose
- From the README and file structure, tsw-cli is a Python-based command-line interface that orchestrates “tiny smart workers” (AI/logic modules) to perform tasks like research, code generation, knowledge lookup, summarization, and writing.
- It also includes an “MCP Server” component (under `mcp/`) for deploying or testing these worker scripts against a local or remote environment.

##### File structure
Top-level:
- `.env.example`, `.gitignore`, `README.md`, `pyproject.toml` – project metadata & config
- `cli.py` – entry point for the command-line tool
- `agent/` – core AI-worker modules:
– `think.py` → orchestration entry
– `research.py`, `code.py`, `summary.py`, `writer.py` – individual worker steps
– `kb.py` – knowledge base interface (PostgreSQL)
– `settings.py` – configuration loader
- `lib/` – shared utilities:
– `utils.py` – helper functions
– `pako.py` – possibly a compression or packing utility
- `mcp/` – scripts to register or explore the workers as services (e.g., `kb_exploer.py`)

##### Key insights from the README
- The CLI loads environment variables (via `.env`), syncs dependencies with `uv`, then runs `cli.py`.
- Each command supports a `--config` to point to alternate settings.
- PostgreSQL (PG) with a default schema `ai` is used for knowledge storage.
- The “MCP Server” section shows how to register or test scripts in a dev environment.

##### Main components
A. CLI Layer (cli.py)
B. Agent Pipeline (agent module)
1. Orchestrator (`think.py`)
2. Worker steps (`research.py` → `code.py` → `summary.py` → `writer.py`)
3. Knowledge Base interface (`kb.py`)
C. Utility Library (`lib/utils.py`, `lib/pako.py`)
D. Configuration & Environment (`.env`, `settings.py`)
E. Data Store (PostgreSQL database schema `ai`)
F. MCP Server (scripts under `mcp/`)
G. External Dependencies (e.g., `uv` CLI tool, Python runtime)

##### Relationships and interactions
- CLI invokes `think.py`, passing CLI args and resolved config.
- `think.py` uses `settings.py` to load environment variables (from `.env` or `--config`).
- The orchestrator calls each worker module in turn, sharing data via in-memory objects.
- When a worker needs facts or context, it calls `kb.py` → issues SQL queries to the PostgreSQL `ai` schema.
- Workers may use `lib/utils.py` for logging, string formatting, retry logic, and `lib/pako.py` for any data packaging.
- MCP scripts (`mcp/kb_exploer.py`) interface with the project via `uv` – registering the script as a service, enabling “dev” mode or “install” mode.

##### Architectural patterns and design principles
- Modular pipeline: each worker is a single-responsibility component.
- Separation of concerns: CLI vs orchestration vs data persistence vs utilities.
- Pluggable config: environment variables + `settings.py` + `--config` override.
- Extensible service registration via the MCP subsystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "tsw-cli (Python)"
        direction TB
        CLI["CLI Layer\n(cli.py)"]:::config
        Config["Config Loader\n(settings.py)"]:::config
        Env["Environment (.env example)"]:::config
        Orchestrator["Agent Orchestrator\n(think.py)"]:::app
        subgraph "Worker Pipeline"
            direction TB
            Research["Research Worker\n(research.py)"]:::app
            CodeGen["Code Generation Worker\n(code.py)"]:::app
            Summarization["Summarization Worker\n(summary.py)"]:::app
            Writing["Writing Worker\n(writer.py)"]:::app
        end
        subgraph "Utilities"
            direction TB
            Helpers["Helpers\n(utils.py)"]:::app
            Packaging["Packaging\n(pako.py)"]:::app
        end
        KBInterface["KB Interface\n(kb.py)"]:::app
    end

    DB["PostgreSQL DB\n(schema: ai)"]:::db
    MCP["MCP Server\n(mcp/kb_exploer.py)"]:::mcp
    UV["uv CLI & lock\n(uv.lock)"]:::extdep
    PyProj["Project Config\n(pyproject.toml)"]:::config
    README["Documentation\n(README.md)"]:::doc

    CLI -->|"invoke\npython cli.py"| Orchestrator
    CLI -.->|loads\nconfig| Config
    CLI -.->|reads\n.env| Env
    Orchestrator -->|"calls"| Research
    Research -->|"calls"| CodeGen
    CodeGen -->|"calls"| Summarization
    Summarization -->|"calls"| Writing
    Orchestrator -->|uses| Helpers
    Orchestrator -->|uses| Packaging
    Orchestrator -->|queries| KBInterface
    KBInterface <-->|"SQL query/result"| DB
    MCP -->|"register scripts\nmcp install"| CLI
    UV -->|"sync deps"| CLI
    UV -->|"sync deps"| MCP
    PyProj --> CLI
    README --> CLI

    click CLI "https://github.com/dteam-top/tsw-cli/blob/main/cli.py"
    click Config "https://github.com/dteam-top/tsw-cli/blob/main/agent/settings.py"
    click Env "https://github.com/dteam-top/tsw-cli/blob/main/.env.example"
    click Orchestrator "https://github.com/dteam-top/tsw-cli/blob/main/agent/think.py"
    click Research "https://github.com/dteam-top/tsw-cli/blob/main/agent/research.py"
    click CodeGen "https://github.com/dteam-top/tsw-cli/blob/main/agent/code.py"
    click Summarization "https://github.com/dteam-top/tsw-cli/blob/main/agent/summary.py"
    click Writing "https://github.com/dteam-top/tsw-cli/blob/main/agent/writer.py"
    click KBInterface "https://github.com/dteam-top/tsw-cli/blob/main/agent/kb.py"
    click Helpers "https://github.com/dteam-top/tsw-cli/blob/main/lib/utils.py"
    click Packaging "https://github.com/dteam-top/tsw-cli/blob/main/lib/pako.py"
    click MCP "https://github.com/dteam-top/tsw-cli/blob/main/mcp/kb_exploer.py"
    click PyProj "https://github.com/dteam-top/tsw-cli/blob/main/pyproject.toml"
    click UV "https://github.com/dteam-top/tsw-cli/blob/main/uv.lock"
    click README "https://github.com/dteam-top/tsw-cli/blob/main/README.md"

    classDef app fill:#D0E8FF,stroke:#003366,color:#003366
    classDef config fill:#E0FFD8,stroke:#336600,color:#336600
    classDef db fill:#FFE0B2,stroke:#CC6600,color:#CC6600
    classDef mcp fill:#EEEEEE,stroke:#777777,color:#555555
    classDef extdep fill:#FFD6E5,stroke:#D00050,color:#D00050
    classDef doc fill:#F0F0F0,stroke:#888888,color:#555555
```
