Technical reference
Architecture
A complete technical reference for SS-1 Signal Shell. Covers the system topology, two-channel communication pattern, LangGraph pipeline, agent model assignments, and the ActionCard JSON contract.
System overview
┌─────────────────────────────────────────────────────────────┐
│ SS-1 Signal Shell │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Tauri v2 Desktop Shell (Rust) │ │
│ │ ┌────────────────────────────────────────────────┐ │ │
│ │ │ React 19 Webview (TypeScript) │ │ │
│ │ │ │ │ │
│ │ │ StatusBar │ MessageStream │ CommandBar │ │ │
│ │ │ │ │ │
│ │ │ Cards: SignalBrief · ManifestDiff · │ │ │
│ │ │ ScanStatus · ExportReady │ │ │
│ │ └────────────┬───────────────────────────────────┘ │ │
│ │ │ Tauri invoke + WebSocket │ │
│ └───────────────┼──────────────────────────────────────┘ │
│ │ │
│ ┌───────────────▼──────────────────────────────────────┐ │
│ │ Python FastAPI Sidecar (port 8001) │ │
│ │ │ │
│ │ /command POST → process_command() │ │
│ │ /approve POST → process_approval() │ │
│ │ /ws WS → broadcast stream │ │
│ │ │ │
│ │ LangGraph Pipeline │ │
│ │ ├── Intent Classifier (Haiku) │ │
│ │ ├── Monitor Node (Haiku + Firecrawl/Tavily) │ │
│ │ ├── Analyst Node (Sonnet) │ │
│ │ ├── Significance Gate (Haiku) │ │
│ │ ├── Propose Node (Sonnet) │ │
│ │ ├── HITL Approval Gate (blocks thread) │ │
│ │ └── Apply Node (GitPython write) │ │
│ │ │ │
│ │ SQLite (local) · manifest.md · git repo │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Two-channel communication
Identical pattern to TX-1 Terminal. Two channels with distinct responsibilities, never mixed.
WebSocket /ws
Persistent streaming channel. Used for everything the user watches in real-time.
- ·Scan log lines (SCANNING, ANALYSING, SCORING)
- ·Status updates (scanning on/off, project name)
- ·ActionCard delivery (SIGNAL_BRIEF, MANIFEST_DIFF, etc.)
- ·Connection confirmation on connect
HTTP REST
Discrete action channel. Used for user-initiated commands and approval decisions.
- ·POST /command — submit a command string
- ·POST /approve — submit an approval decision
- ·GET /state — current in-memory state
- ·GET /health — sidecar liveness check
LangGraph pipeline topology
Intent Classifier (Haiku — fast routing)
│
▼
Monitor Node (Haiku — OSINT crawl via Firecrawl/Tavily)
│
▼
Analyst Node (Sonnet — compare new data against manifest)
│
▼
Significance Gate (Haiku — score 0-100)
├── score < 40 → log silently, return to Monitor
└── score ≥ 40 →
│
▼
Propose Node (Sonnet — generate intelligence brief)
│
▼
HITL Approval Gate ← blocks thread, awaits user signal
├── approve → Apply Node (GitPython manifest write + git commit)
├── save → DB only, manifest unchanged
└── dismiss → log rationale, END
Circuit breaker: scan loops are capped at 10 iterations per session. A "Scan Limit Reached" INFO card halts the pipeline.
Agent model assignments
| Task | Model | Reason |
|---|---|---|
| Intent classification, scan routing | claude-haiku-4-5 | Speed. JSON only output. No prose. |
| OSINT data extraction, field parsing | claude-haiku-4-5 | Pattern matching. Cost-efficient. |
| Significance scoring (0–100) | claude-haiku-4-5 | Simple score + rationale. Fast loop. |
| Competitive analysis, brief generation | claude-sonnet-4-6 | Quality. The brief is the product. |
| Manifest diff reasoning | claude-sonnet-4-6 | Nuanced semantic comparison required. |
Never use Opus for anything real-time. Never use Haiku for brief generation — brief quality is the core product value.
ActionCard JSON contract
All agent outputs are delivered as ActionCards over the WebSocket stream. Card state is owned by the backend. The frontend only renders.
{
"card_id": "uuid",
"type": "SIGNAL_BRIEF | MANIFEST_DIFF | SCAN_STATUS | EXPORT_READY",
"severity": "CRITICAL | WARNING | INFO",
"content": { "title": "...", "summary": "...", ... },
"actions": [
{ "label": "UPDATE MANIFEST", "variant": "primary", "shortcut": "⌘↵", "action": "update_manifest" },
{ "label": "SAVE BRIEF", "variant": "secondary", "shortcut": "⌘B", "action": "save_brief" },
{ "label": "DISMISS", "variant": "ghost", "shortcut": "Esc", "action": "dismiss" }
]
}SIGNAL_BRIEF
Primary intelligence output. Rendered when a signal passes the significance gate. Contains brief, diff, and strategic options.
MANIFEST_DIFF
Rendered after an approved manifest update or when viewing history. Shows git diff in human-readable format.
SCAN_STATUS
Streaming status during a market sync. Also used for project init confirmation. No action row while scanning.
EXPORT_READY
Rendered after a successful brief export. Shows filename, filepath, word count, and reveal/open actions.
SQLite schema
-- One active project = one manifest CREATE TABLE projects ( id TEXT PRIMARY KEY, name TEXT NOT NULL, manifest_path TEXT NOT NULL, git_repo_path TEXT NOT NULL, created_at TEXT NOT NULL, last_synced TEXT ); -- Tracked competitor entities per project CREATE TABLE competitors ( id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), name TEXT NOT NULL, urls TEXT NOT NULL, -- JSON array active INTEGER DEFAULT 1 ); -- Individual detected changes from OSINT CREATE TABLE signals ( id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), competitor_id TEXT REFERENCES competitors(id), detected_at TEXT NOT NULL, source_url TEXT, raw_content TEXT, significance_score INTEGER, significance_rationale TEXT, status TEXT DEFAULT 'pending' -- pending | surfaced | dismissed | actioned ); -- Generated intelligence outputs CREATE TABLE briefs ( id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), signal_ids TEXT NOT NULL, -- JSON array generated_at TEXT NOT NULL, title TEXT NOT NULL, content_md TEXT NOT NULL, status TEXT DEFAULT 'draft', -- draft | approved | exported export_path TEXT ); -- Git commit history mirror for UI display CREATE TABLE manifest_versions ( id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), commit_hash TEXT NOT NULL, committed_at TEXT NOT NULL, change_summary TEXT, triggered_by TEXT -- signal_id or 'user' ); -- Every agent action, verbatim (same pattern as TX-1) CREATE TABLE audit_log ( id TEXT PRIMARY KEY, project_id TEXT, action_type TEXT NOT NULL, rationale TEXT, input_hash TEXT, output_hash TEXT, created_at TEXT NOT NULL );
Architecture Decision Records
ADR-001
acceptedUse Tauri v2 as the desktop shell
Matches TX-1 exactly. Rust binary wrapping a React webview. No Electron, no Electron tax.
ADR-002
acceptedManifest as a git-backed markdown file
Human-editable, diffable, portable. The commit log is the audit trail.
ADR-003
acceptedHITL approval required for all manifest writes
No agent updates product strategy without review. The approval is the product.
ADR-004
acceptedLangGraph for pipeline orchestration
Typed state, separable nodes, inspectable checkpoints. Prefer over single-agent tool-use.
ADR-005
acceptedSQLite for all local persistence
No server, no sync, no ops. Matches TX-1 data layer exactly.
ADR-006
acceptedGitPython for all git operations
Never shell out to git directly. Consistent interface, better error handling.
ADR-007
acceptedMock data pipeline for v1 demo
Deterministic, reproducible, no external API dependencies. Swappable in one file.
ADR-008
acceptedBlue as SS-1 accent colour (monitoring state)
Blue ≠ green (confirmed action) ≠ amber (review required) ≠ rose (critical). Blue = intelligence/monitoring.