SS-1

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

TaskModelReason
Intent classification, scan routingclaude-haiku-4-5Speed. JSON only output. No prose.
OSINT data extraction, field parsingclaude-haiku-4-5Pattern matching. Cost-efficient.
Significance scoring (0–100)claude-haiku-4-5Simple score + rationale. Fast loop.
Competitive analysis, brief generationclaude-sonnet-4-6Quality. The brief is the product.
Manifest diff reasoningclaude-sonnet-4-6Nuanced 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

accepted

Use Tauri v2 as the desktop shell

Matches TX-1 exactly. Rust binary wrapping a React webview. No Electron, no Electron tax.

ADR-002

accepted

Manifest as a git-backed markdown file

Human-editable, diffable, portable. The commit log is the audit trail.

ADR-003

accepted

HITL approval required for all manifest writes

No agent updates product strategy without review. The approval is the product.

ADR-004

accepted

LangGraph for pipeline orchestration

Typed state, separable nodes, inspectable checkpoints. Prefer over single-agent tool-use.

ADR-005

accepted

SQLite for all local persistence

No server, no sync, no ops. Matches TX-1 data layer exactly.

ADR-006

accepted

GitPython for all git operations

Never shell out to git directly. Consistent interface, better error handling.

ADR-007

accepted

Mock data pipeline for v1 demo

Deterministic, reproducible, no external API dependencies. Swappable in one file.

ADR-008

accepted

Blue as SS-1 accent colour (monitoring state)

Blue ≠ green (confirmed action) ≠ amber (review required) ≠ rose (critical). Blue = intelligence/monitoring.