SwarmLite

Architecture

Technical decisions
and system design

Every technology choice in Swarm Lite is deliberate and defensible. This page documents the stack, the reasoning, and the trade-offs.

System Overview

Next.js 16 (App Router)IBM Carbon Design SystemFastAPI (Python)LangGraphAnthropic ClaudeSQLite@carbon/pictograms-react
┌─────────────────────────────────────────────────┐
│                   Browser                        │
│  Next.js 16 + IBM Carbon + localStorage          │
│  ┌──────────┬──────────────────┬──────────────┐  │
│  │ Sidebar  │   Main Content   │ Context Panel│  │
│  │  (nav)   │ + Chat Drawer    │  (context)   │  │
│  └──────────┴──────────────────┴──────────────┘  │
└─────────────┬───────────────────────────────────┘
              │ REST / WebSocket
┌─────────────┴───────────────────────────────────┐
│            FastAPI Sidecar (Python)               │
│  ┌──────────────────────────────────────────────┐│
│  │  LangGraph Agent Graph                       ││
│  │  ┌──────────┐  ┌──────────┐  ┌───────────┐  ││
│  │  │ Persona  │  │ Market   │  │ Report    │  ││
│  │  │ Response │  │ Scanner  │  │ Generator │  ││
│  │  └──────────┘  └──────────┘  └───────────┘  ││
│  └──────────────────────────────────────────────┘│
│  Anthropic Claude (Sonnet + Haiku)               │
│  SQLite (persistence)                            │
└─────────────────────────────────────────────────┘

Stack Decisions

Frontend

Next.js 16 + React 19

App Router for file-based routing, React Server Components for performance, client components for interactive features (forms, chat drawer). The same framework powers the portfolio website, keeping the trilogy consistent.

UI Framework

IBM Carbon Design System

Enterprise credibility demands enterprise design. Carbon provides accessible, production-ready components (Modal, TextInput, Button, Toggle) with design tokens that ensure visual consistency. Tailwind was removed after discovering CSS conflicts with Carbon — pure Carbon proved more reliable.

Backend

FastAPI (Python)

Python is the native language for AI/ML tooling. FastAPI provides async support, WebSocket capability for streaming persona responses, and automatic OpenAPI documentation. The sidecar pattern keeps the frontend and AI layer independently deployable.

Agent Orchestration

LangGraph

Multi-persona huddles require graph-based orchestration — not simple sequential chains. LangGraph manages the persona response graph: route query → fan out to N personas → collect responses → generate report. Circuit breakers and approval gates are graph nodes.

LLM

Anthropic Claude

Sonnet for substantive persona analysis (deep, contextual responses). Haiku for routing and scoring (fast, cheap classification). Token budgets per session prevent runaway costs. The model is called via langchain-anthropic.

Persistence

SQLite → PostgreSQL

SQLite for MVP simplicity — zero config, single file, works locally. The schema is designed for PostgreSQL migration when multi-tenant deployment requires it. localStorage bridges the gap for the demo.

Data Model

Account

id, name, industry, created_at

Market

id, account_id, name, competitors[], watch_items[], scan_interval

Persona

id, account_id, type, name, demographic, psychographic, goals[], pain_points[]

Project

id, account_id, name, description, market_ids[], manifest

Session

id, project_id, title, type, persona_ids[], status, parent_session_id?

Message

id, session_id, role, persona_id?, content, created_at

Artefact

id, session_id?, project_id, type, title, content, format

Action

id, project_id, description, status, resource_cost

ChatThread

id, context, messages[], created_at