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

Design Principles

Open/Closed Principle

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

# 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.

@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.