Technical Stack

This document describes the full technical stack behind the ContextSync reference implementation. It is written for judges who want to understand the engineering decisions, not just the protocol design.

Architecture Overview

  Browser (judges)
       |
       | HTTPS :4112
       v
  +-------------------+
  | Next.js 14        |  Dashboard, landing page, playground UI
  | App Router        |  Tailwind CSS + IBM Plex fonts
  | React 18          |  Server Components for initial data
  | SSE via proxy     |  Client Components for live state
  +--------+----------+
           |
           | HTTP proxy (server-side, localhost only)
           v
  +-------------------+
  | Express.js        |  ContextSync protocol server
  | Node.js 20        |  REST API + SSE hub
  | Port :4111        |  Simulation engine
  |                   |  Playground agent (Groq)
  +--------+----------+
           |
     +-----+------+
     |            |
  +--v---+   +---v-----------+
  | SQLite|   | Filesystem    |
  | WAL   |   | SHA-256 blobs |
  +-------+   +---------------+

Protocol Server

Runtime: Node.js 20.19 (ES modules, native fetch, --env-file-if-exists)

Framework: Express.js 4.19. Chosen for simplicity and ecosystem maturity. The entire API surface is ~600 lines of route handlers plus ~200 lines of core logic.

Database: SQLite via the sqlite3 npm package with the sqlite promise wrapper. WAL (Write-Ahead Logging) mode enabled at connection time for concurrent read performance. Foreign keys enforced. Seven tables: actors, artifacts, artifact_versions, permissions, subscriptions, change_events, provenance. Indexed on URI, actor, timestamp, and domain.

Blob storage: Artifact payloads are stored as files on the local filesystem, named by their SHA-256 content hash. The version table stores a pointer (blob_hash) to the file. This keeps the SQLite database small (metadata only) and makes deduplication free — identical content produces identical hashes.

Diff engine: The diff npm package (line-level diff). Diffs are computed at write time and stored alongside change events so the dashboard can render them without recomputation.

SSE hub: An in-memory fan-out hub. Subscribers are keyed by subscription ID and hold an Express response object plus a glob pattern. When a change event is published, the hub iterates all subscribers and writes an SSE frame to every response whose pattern matches the event's artifact URI. Heartbeats every 15 seconds keep proxies from closing idle connections.

Permission evaluator: Evaluates (actor, artifact_uri, operation) against the permissions table. Supports exact actor_id grants and agent_class grants. Artifact patterns use glob matching: * matches a single path segment, ** matches across slashes. Default-deny: no matching grant means access denied.

Provenance logger: Writes an append-only row on every read and write operation. Each row records actor, operation, artifact URI, version touched, optional downstream URI, and timestamp. The log is never updated or deleted.

Simulation Engine

Architecture: A server-side controller (sim/engine.js) that runs scripted scenarios against the real protocol surface. Each scenario defines a sequence of "beats" — time-delayed actions that actors perform (read or write an artifact). Beats are scheduled via setTimeout; stop() clears all pending timers.

Scenarios: Three industry-specific narratives (fintech SEC rule, healthcare FDA update, enterprise EU AI Act cascade), each with 13-15 beats over ~20 seconds. Every beat goes through the same readArtifactOp and writeVersionOp helpers the HTTP routes use, so it produces real change events, real provenance records, and real SSE notifications.

Events: The simulation emits sim.beat, sim.read, sim.write, sim.started, sim.completed events to the SSE hub. These are consumed by the dashboard's simulation page to animate actor highlights, artifact version bumps, and the narrative feed.

AI Playground

Model: openai/gpt-oss-120b via the Groq API. OpenAI-compatible tool-calling interface.

Agent actor: agent-playground-assistant with class playground-assistant, granted read access on *. Bootstrapped idempotently at server start.

Tools (7): list_organizations, list_domains, list_artifacts, read_artifact, get_artifact_history, search_artifacts, list_permissions. Every tool call goes through the real ContextSync API as the playground agent, producing real provenance rows.

Loop: The chat endpoint sends the conversation history plus system prompt to Groq with tool specs. If the model returns tool_calls, the server executes them, adds the results to the message history, and calls Groq again. Up to 6 iterations. Tool call events are published to the SSE hub so the dashboard shows live activity.

Robustness: Assistant messages are normalized before re-sending to Groq (ensuring type: 'function' on every tool_call). Raw <function=...> fallback parsing catches cases where the model emits Llama-native tool call format instead of OpenAI-compatible schema.

Dashboard & Hosting

Framework: Next.js 14 with App Router. Mix of Server Components (for initial data fetch) and Client Components (for SSE subscriptions and interactive state). Statically exported to pure HTML/JS/CSS — no server runtime in production.

Hosting: Firebase Hosting on Google Cloud Platform. The static export is deployed to Firebase's global CDN with immutable cache headers (1 year) on /_next/static/ and /audio/ assets. Clean URLs enabled. Production URL: contextsync-devfest.web.app.

Styling: Tailwind CSS 3.4 with custom design tokens. Light theme only. Background: #FAFAF7 (warm off-white). Accent: #3ECF8E (Supabase-inspired emerald). Typography: Inter for UI, IBM Plex Serif for headings and artifact names, IBM Plex Mono for URIs, diffs, and code.

Pages: 17 routes covering landing page, video, whitepaper, stack, enterprise architecture, agent skill prompt, business model, overview dashboard, simulation theatre, playground, protocol spec, organizations (org chart), artifacts (list + drill-down with diff viewer), actors, live changes (SSE), permissions, and provenance.

CLI

Framework: Commander.js 12. Single ctx binary with subcommands covering every protocol verb.

Transport: Native fetch (Node 20) for HTTP, native EventSource-compatible streaming for SSE subscriptions.

Config: ~/.contextsync/config.json stores the server URL and acting actor_id. ctx init and ctx use manage it.

Commands: init, use, status, explore, artifacts, actor create/list, artifact create/get/put/history/diff, changes, subscribe, permission grant/list/explain, provenance.

AI & Media Services

Groq (LLM inference): Powers the AI Playground agent. The Groq API provides low-latency inference with an OpenAI-compatible tool-calling interface. Model: openai/gpt-oss-120b. The playground agent uses 7 read-only tools to query organizational context through the live protocol.

HeyGen (video generation): Used to produce the 2-minute explainer video on the landing page. AI-generated avatar narrates the protocol's problem statement, five primitives, and evaluation results. Hosted on Cloudinary for adaptive streaming.

ElevenLabs (text-to-speech): Generates audio narration of the whitepaper for the listen feature on the whitepaper page. The TTS endpoint is called server-side with the ELEVENLABS_API_KEY environment variable. Output cached as static audio.

Security Model

• Auth (v0.1): API-key style via X-Actor-Id header. Every request identifies which actor is performing the action.
• Permissions: default-deny, evaluated on every artifact operation. Supports actor-level and class-level grants with glob patterns.
• Secrets: GROQ_API_KEY loaded via Node 20's --env-file-if-exists from .env.local (gitignored). Never logged, never sent to the browser.
• Firewall: ufw active. Only ports 22/80/443/4112 open. Protocol server (4111) is localhost-only; the dashboard proxies to it.

What We Would Change for Production

Team

ContextSync | DevFest 2026 | WashU