Architecture

How Suitcase works under the hood.

High-Level Overview

┌──────────────────────────────────────────────────────────┐
│                      Your Machine                        │
│                                                          │
│  ┌──────────┐   ┌──────────┐   ┌────────────────────┐  │
│  │  Browser  │   │ Discord  │   │    LLM Endpoint    │  │
│  │  (React)  │   │   Bot    │   │ (Relay / API)      │  │
│  └────┬─────┘   └────┬─────┘   └─────────┬──────────┘  │
│       │              │                   │              │
│       ▼              ▼                   │              │
│  ┌──────────────────────────┐            │              │
│  │   Suitcase FastAPI App   │────────────┘              │
│  │   (Python, port 8000)    │                           │
│  │                          │                           │
│  │  ┌────────────────────┐  │                           │
│  │  │  Synax Bridge (JS) │  │  ◄── Super Edition        │
│  │  │  IPC tool execution│  │      runtime wrapper      │
│  │  └────────────────────┘  │                           │
│  │                          │                           │
│  │  ┌────────────────────┐  │                           │
│  │  │  suitcase_world/   │  │  ◄── All agent writes     │
│  │  │  SELF.md WORLD.md  │  │      confined here        │
│  │  │  SOUL.md artifacts │  │                           │
│  │  └────────────────────┘  │                           │
│  └──────────────────────────┘                           │
└──────────────────────────────────────────────────────────┘

Components

FastAPI Server (Python)

The main application server. Handles:

• REST API for the React frontend
• Career profile and evidence management
• Resume parsing and job lead tracking
• LLM configuration and verification
• Setup wizard orchestration

Synax Bridge (Node.js)

A thin subprocess bridge that wraps the LLM inference. Runs as a child process spawned by Python. Handles:

• Model configuration and API calls
• Tool execution via IPC (Python executes tools, bridge relays to model)
• Streaming diagnostics and event reporting
• The bridge uses Synax Runtime: Super Edition — a wrapper that reads world context files and supports message/dream/pulse run kinds.

React Frontend

A TypeScript + Vite SPA served by the FastAPI server. Pages:

• Setup wizard — profile, sources, resume, LLM config
• Admin console — status dashboard, safety checks, controls
• Chat — conversation with Suitcase

World System

Suitcase maintains a living directory at suitcase_world/ that defines its identity and operating boundaries:

File	Purpose
WORLD.md	World laws — sandbox boundaries, safety rules, authority hierarchy
SOUL.md	Voice, personality, conversational stance, boundaries, trust principles
SELF.md	Mutable self-model — operating style, initiative rules, reflection policy
CHECKINS.md	Daily check-in policy (Discord only)

These files are runtime context, not higher-priority instructions. The system prompt defines the immutable identity and security boundaries. The world files provide operating memory that Suitcase can reflect on and propose changes to.

For a deeper treatment of write boundaries, review gates, and secret handling, see Sandboxing & Security.

Model Choice & Security

The model you choose affects Suitcase's security posture. Smaller models are more susceptible to prompt injection and instruction-following failures. The system prompt contains security boundaries that the model must respect — a model that can't reliably follow complex instructions may inadvertently violate these boundaries.

Verified model: The smallest model we've tested and confirmed working well is Gemma 4 26B MoE (A4B active) IQ4_XS quantized via Relay with llama.cpp. This model reliably follows the system prompt, respects world boundaries, and maintains Suitcase's personality.

For cloud providers, GPT-4o-mini and Claude Haiku are sufficient. Smaller local models (<8B) are not recommended for security-sensitive conversations.