> ## Documentation Index
> Fetch the complete documentation index at: https://www.swaitch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How swAItch is built — SOLID principles, module responsibilities, and data flow

# Architecture

swAItch follows **SOLID principles** with a clean, modular design that makes it easy to extend and maintain.

## Module Map

```
src/swaitch/
├── server.py          # FastMCP server + lifespan management
├── models.py          # Pydantic v2 data models (shared language)
├── config.py          # Platform-aware path resolution
├── tools.py           # MCP tool definitions
├── watcher.py         # Async file system watcher
├── sync.py            # Synchronization layer (Parsers -> DB)
├── db/                # Central SQLite database package
│   ├── session.py     # SQLAlchemy setup and session management
│   └── models.py      # SQLAlchemy ORM definitions
└── parsers/
    ├── base.py        # Abstract BaseParser contract
    ├── registry.py    # Parser registry (discovery + lookup)
    └── cursor.py      # Cursor IDE parser
```

## Data Flow

```mermaid theme={null}
sequenceDiagram
    participant Client as MCP Client
    participant Server as FastMCP Server
    participant Tools as tools.py
    participant DB as swaitch.db (SQLite)
    participant Sync as sync.py
    participant Parser as CursorParser
    participant IDE_DB as IDE Storage (state.vscdb)

    Note over Server,IDE_DB: Background Sync (On Startup & File Changes)
    Server->>Sync: Background Thread Trigger
    Sync->>Parser: list_conversation_ids()
    Parser->>IDE_DB: query IDs
    Parser-->>Sync: ["uuid-1", "uuid-2"]
    Sync->>Parser: get_conversation("uuid-1")
    Parser->>IDE_DB: read full row + JSON
    Parser-->>Sync: Conversation Object
    Sync->>DB: Upsert Conversation & Messages

    Note over Client,DB: Tool Call Execution (Fast)
    Client->>Server: call tool (list_conversations)
    Server->>Tools: dispatch
    Tools->>DB: query available rows
    DB-->>Tools: lightweight rows
    Tools-->>Client: {conversations: [...]}
```

## Design Principles

### Open/Closed Principle

New IDE parsers are added by creating a new class that extends `BaseParser`. No existing code is modified.

```python theme={null}
# Adding Windsurf support — zero changes to existing files
class WindsurfParser(BaseParser):
    ...
```

### Dependency Inversion

Tools depend entirely on the central `swaitch.db`, never directly on parsers. Parsers are orchestrated exclusively by `sync.py`.

```python theme={null}
@mcp.tool
def list_conversations(source: str):
    session = get_session()
    # Query the central normalized database directly
    return session.query(ConversationRow).filter_by(source=source).all()
```

### Single Responsibility

| Module                | Responsibility                          |
| --------------------- | --------------------------------------- |
| `models.py`           | Data structures                         |
| `config.py`           | Path resolution                         |
| `parsers/base.py`     | Parser contract                         |
| `parsers/registry.py` | Parser discovery                        |
| `parsers/cursor.py`   | Cursor-specific parsing                 |
| `db/models.py`        | SQLAlchemy local cache schemas          |
| `db/session.py`       | SQLAlchemy connection pool              |
| `sync.py`             | Synchronizing parsers into `swaitch.db` |
| `tools.py`            | MCP tool definitions (reads from DB)    |
| `watcher.py`          | File system monitoring (triggers sync)  |
| `server.py`           | Wiring everything together              |

## File Watcher

The watcher runs as an async background task during server lifespan:

1. Collects watch paths from all available parsers
2. Uses `watchfiles` (Rust-based) for efficient monitoring
3. On change → triggers `sync.py` in a background thread pool
4. Next tool call picks up fresh data instantly from the local `swaitch.db` sqlite file

No polling, no stale data.