Skip to main content

​
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

ModuleResponsibility
models.pyData structures
config.pyPath resolution
parsers/base.pyParser contract
parsers/registry.pyParser discovery
parsers/cursor.pyCursor-specific parsing
db/models.pySQLAlchemy local cache schemas
db/session.pySQLAlchemy connection pool
sync.pySynchronizing parsers into swaitch.db
tools.pyMCP tool definitions (reads from DB)
watcher.pyFile system monitoring (triggers sync)
server.pyWiring 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.