# Monoco Toolkit Architecture

Monoco Toolkit is a modular toolchain based on Python, designed to provide a consistent development experience for both Agents and Humans. This architecture follows DDD (Domain-Driven Design) principles.

## 1. Core Architectural Patterns

### 1.1 Filesystem as SSOT (Single Source of Truth)

**Truth resides on the disk, not in memory.**

- **Data Persistence**: All business states (Issues, Spikes, Configs) must be persisted in the filesystem in human-readable formats (Markdown/YAML/JSON).
- **Module Decoupling**: Direct business data transfer between modules via memory calls is **prohibited**. Feature A should not directly call standard Python functions of Feature B. All interactions must be mediated by the filesystem.
  - _Bad_: `issue_manager.add_dependency(spike_id)`
  - _Good_: `Issue` module reads the `.md` file generated by the `Spike` module to validate references.

### 1.2 Lifecycle Separation

The Toolkit comprises two distinct runtime lifecycles:

- **CLI (Command Line Interface)**: **Transient**.
  - Not just a tool for humans, but the "hands" of the Agent.
  - Each invocation is an independent process: Start -> Execute -> Exit.
  - Stateless; re-hydrates context from the FS on every run.
- **Daemon**: **Long-running**.
  - Serves as the backend for the UI (Kanban).
  - Maintains memory caches (Watcher) to provide high-performance reads and push updates (SSE).
  - **Not the source of truth**; it is merely a "high-performance view" of the filesystem.

### 1.3 Bootstrapping & Init

Every feature module must be "Self-Bootstrapping".

- **Init Interface**: Each module (e.g., `issue`, `spike`) must implement an `init` subcommand.
- **On-Demand Activation**: Users (or Agents) should not be forced to adopt the entire suite. One can activate only the Spike functionality via `monoco spike init`.
- **Convention over Configuration**: `init` should generate standard directory structures and default configurations, making the module immediately usable.

## 2. Module Standards

The Toolkit adopts a plugin-based architecture, where each Feature resides in an independent directory.

```text
Toolkit/monoco/features/
├── issue/
│   ├── commands.py   # CLI Entry Point
│   ├── service.py    # Business Logic (CRUD)
│   ├── models.py     # Pydantic Models
│   └── daemon.py     # FastAPI Routes (Optional)
├── spike/
│   └── ...
└── ...
```

## 3. Cross-Module Collaboration

While direct memory coupling is prohibited, modules need to collaborate. We achieve this via **"Soft Linking"** and **"Standard Protocols"**.

- **Reference Protocol**: E.g., `[[ticket-id]]` or `Ref: <ID>`. Each module is responsible for parsing standard text patterns.
- **Public Interfaces**: If interaction is strictly necessary, modules should expose an explicit `PublicAPI` class, strictly for read-only queries, never for modifying another module's state.
