A unified, sovereign realtime substrate in Rust: one durable event spine (Apache Iggy), one multiplexed client socket, and separate transports for media, peer CRDT sync, and federation. This repository is the contract-first monorepo for the core, the gateway, and every SDK.
For Claude Code and all agent systems: Read
CLAUDE.mdanddocs/PROMETHEUS-BASE-RULES.md(Rules 1–40) before generating any code. Readdocs/IMPLEMENTATION-PLAN.md(RFC-FRF-002) in full before generating any code. Follow the phase order exactly. Do not skip the contract-freeze gate. Halt at each phase boundary for explicit approval.
Phase 18 — media, federation & auth-flow (complete). Phases 16–17 hardened the
security boundary, shipped the core deliverables, and completed the pure-Rust planes;
phase 18 fixed the remaining correctness bugs and completed the scoped deferred planes
(Matrix inbound, ATProto outbound, a str0m WebRTC-negotiation spike, admin-ui token
hardening, and a Dart transport shim). The workspace builds clean and every CI gate is
green — see docs/PHASE-18-SIGNOFF.md and the CHANGELOG.
Phase-18 highlights: the str0m signaling routing bug is fixed (unicast/room fan-out,
no self-echo); Matrix inbound streams real /sync events (no Tuwunel dep); ATProto
outbound writes to a PDS; the str0m negotiation round-trip is proven (full media loop
deferred); admin-ui auto-logs-out on token expiry / gateway 401. Still deferred (gated
off, documented in docs/SECURITY.md §6): full sovereign SFU media, LiveKit cross-node
inbound, full OIDC login, and ATProto outbound gateway wiring.
The phase-16/17 summary below still holds:
- Security (hardened in 16, re-verified in 17): production
compose.ymlcannot carry the dev auth bypass (the override is now untracked); app-layer tenant-equality guard on publish;JWT_ISSUERmandatory in production;clippy::unwrap_usedenforced in CI; rate-limit / body-size / CORS middleware; Cedar surfaces policy errors. An independent re-audit found zero CRITICAL and zero HIGH in the production build. - All six proto services are live: Spine, Signal, Sync, Agent, plus the phase-17
EntityService(auth-guarded read/watch) andAuthzService(Keto-backed, tenant-scoped) gateway servers. - SDKs & CLI:
frf-sdk-rustbinds all services; FFI (Swift/Kotlin) transport with resilient reconnect +ack; TS/Go/C# wrappers cover all six services;frf-cliadds broker-offset inspect and CDC slot management; Dart CRDT bindings generated viauniffi-bindgen-dart. All SDKs generate from the frozenproto-v1. - Operability:
/readyz,/metrics, graceful shutdown, boot-time config validation, Keto migration step. - Docs: env reference, runbook, security model, API reference, and this state.
Deferred to a future phase (documented, not silently missing): str0m sovereign SFU real
WebRTC (signaling-only today, gated off), Matrix/ATProto federation + LiveKit cross-node
relay, admin-ui interactive OIDC login, and the Dart async-transport bindings
(pending an upstream uniffi-bindgen-dart fix).
See .kbd-orchestrator/current-waypoint.json for the live orchestration state and
.kbd-orchestrator/phases/ for per-phase plans, assessments, and reflections.
flint-realtime-fabric/
├── proto/flint/v1/ # THE CONTRACT — frozen at proto-v1
├── crates/
│ ├── frf-domain/ # Layer 0: pure types, serde only, zero infra deps
│ ├── frf-ports/ # Layer 1: trait seams (no implementations)
│ ├── frf-app/ # Layer 1: use-cases against ports only
│ ├── frf-proto/ # generated from proto/ via tonic-build
│ ├── frf-broker-iggy/ # Adapter: LogBroker → Apache Iggy
│ ├── frf-authz-keto/ # Adapter: AuthzProvider → Ory Keto
│ ├── frf-identity-ory/ # Adapter: IdentityVerifier → Kratos/flint-gate (JWT)
│ ├── frf-policy-cedar/ # Adapter: action policy → Cedar
│ ├── frf-postgres-cdc/ # Adapter: WAL logical replication → spine
│ ├── frf-crdt/ # Adapter: Loro CRDT engine + CrdtStore
│ ├── frf-store-surreal/ # Adapter: server persistence (SurrealDB 3.x)
│ ├── frf-store-redb/ # Adapter: on-device op-log (redb)
│ ├── frf-media-str0m/ # Adapter: sovereign SFU signaling
│ ├── frf-media-livekit/ # Adapter: hosted conferencing signaling
│ ├── frf-bridge-matrix/ # Adapter: Tuwunel projection
│ ├── frf-bridge-atproto/ # Adapter: Tranquil firehose projection
│ ├── frf-agentproto/ # AG-UI / A2A / A2UI schemas + ContentBlock
│ ├── frf-librefang/ # ractor publish/consume actors (BossFang)
│ ├── frf-gateway/ # Interface: Axum 0.8.8, WS mux + gRPC + Connect
│ ├── frf-cli/ # Interface: ops + dev CLI
│ ├── frf-ffi/ # SDK: UniFFI scaffold → Swift, Kotlin
│ └── frf-wasm/ # SDK: wasm-bindgen → browser TS (Loro CRDT)
├── sdks/ # generated/bound — not hand-edited
│ ├── go/ ts/ csharp/
│ ├── swift/ kotlin/ dart/
│ └── entity-management/ # thin RealtimeAdapter on TS SDK
├── admin-ui/ # React 19 / Vite 7 / shadcn-ui / Base UI
│ └── src/features/ # feature-based clean architecture
├── scripts/
│ ├── smoke-cdc.sh # CDC replication slot smoke test
│ └── bench-regression-check.sh
├── dagger/
│ └── codegen.ts # 10-stage CI pipeline
├── docs/
│ ├── IMPLEMENTATION-PLAN.md # RFC-FRF-002 (authoritative build plan)
│ ├── PROMETHEUS-BASE-RULES.md # Rules 1–40 for all agents
│ └── decisions/ # Architecture Decision Records
├── openspec/changes/ # OpenSpec change proposals (active + archive)
├── .kbd-orchestrator/ # KBD orchestration state (travels with repo)
└── Cargo.toml # [workspace] manifest
Feature-based hexagonal. frf-domain holds pure types (serde only, no I/O).
frf-ports defines trait seams (LogBroker, AuthzProvider, IdentityVerifier,
CrdtStore, MediaSignaler, FederationBridge). frf-app orchestrates
use-cases against ports only. Every frf-* adapter crate implements exactly one
port and is selected by Cargo features, so a deployment compiles only the planes
it runs. frf-gateway (Axum 0.8.8) is the deployable: WebSocket mux + tonic gRPC
- Connect-ES.
The dependency rule is absolute and points inward:
Domain (frf-domain)
↑ imported by
Application (frf-app, frf-ports)
↑ imported by
Infrastructure adapters (frf-broker-*, frf-authz-*, ...)
↑ wired by
Interface (frf-gateway)
Nothing in frf-domain or frf-app may import an adapter crate. The compiler
enforces this by keeping adapter crates out of frf-domain and frf-app
[dependencies]. Composition happens in frf-gateway only.
All agents (Claude Code, Codex, Gemini CLI, Roo, Cline, Kilo Code, Librefang, and any Prometheus/UAR-compatible agent) operating in this repository must follow docs/PROMETHEUS-BASE-RULES.md (Rules 1–40).
Key principles:
| Rule | Principle |
|---|---|
| 1 | Think before coding — surface tradeoffs first |
| 2 | Simplicity first — minimum code that solves the problem |
| 3 | Surgical changes — touch only what is necessary |
| 4 | Goal-driven execution — define success criteria first |
| 5 | Truth over fluency — never invent APIs or behavior |
| 8 | Minimize irreversible actions — confirm before destructive ops |
| 11 | Architecture before code — understand the system first |
| 12 | Open standards first — MCP, A2A, AG-UI, WASM, OpenAPI |
| 16 | Strict layering is mandatory — domain ← app ← infra ← interface |
| 25 | Human override always exists |
| 30 | Tests are part of completion |
| 33 | Security is not optional |
| 40 | Stop when done |
Project-specific constraints in CLAUDE.md add stricter requirements on top of
these base rules (see Rule 26).
CLAUDE.md in this repository extends the base rules with project-specific
constraints:
- File size limit: no file over 500 lines
- Absolute dependency rule: enforced by Cargo — domain never imports adapters
- No
unwrap()/expect()in library crates —thiserror+anyhowonly at binary edges clippy::pedantic+deny(warnings)must pass on every commit#[non_exhaustive]on all public enums- Newtype IDs with
#[repr(transparent)] - One port per adapter — no adapter implements two ports
- Proto contract is frozen —
flint/v1/*.protois immutable; breaking changes = new version - Phase gate protocol — halt at each phase boundary for explicit operator approval
# Compilation check (fast)
cargo check --workspace
# Run all tests
cargo test --workspace
# Clippy (CI-equivalent)
cargo clippy --workspace --all-targets -- -D warnings -W clippy::pedantic
# Format check (CI)
cargo fmt --check --all
# Format (apply)
cargo fmt --all
# Build release
cargo build --workspace --release
# Run gateway
cargo run -p frf-gateway
# Admin UI
cd admin-ui && pnpm install && pnpm dev
# Dagger CI pipeline
dagger run ts-node dagger/codegen.ts
# Layer 3 E2E (requires Docker host with DinD)
ENABLE_INTEGRATION_STAGE=true dagger run ts-node dagger/codegen.ts
# CDC smoke test (requires running compose stack)
bash scripts/smoke-cdc.sh| Concern | Choice |
|---|---|
| Web / gateway | Axum 0.8.8 |
| gRPC | tonic + prost |
| Actors (BossFang) | ractor (LibreFang) |
| Event spine | Apache Iggy (GQAdonis fork) behind LogBroker |
| Identity | Ory Kratos + flint-gate (JWT proxy + minting) |
| AuthZ | Ory Keto (Zanzibar) + Cedar (PAUX-1) |
| CRDT engine | Loro 1.13.1 (decision: ADR-001) |
| On-device store | redb |
| Server store | SurrealDB 3.x |
| Postgres | PostgreSQL 17 (CDC via logical replication slot) |
| Media SFU | str0m (sovereign) / LiveKit (hosted) |
| Federation | Tuwunel (Matrix), Tranquil (ATProto) |
| FFI bindings | UniFFI (Swift, Kotlin, Dart via uniffi-bindgen-dart) — ADR-003 |
| Browser transport | Connect-ES + WS mux |
| CI | Dagger (10-stage pipeline) |
| Admin UI | React 19 + Vite 7 + shadcn-ui + Base UI (latest) |
Only Rust is hand-written. Everything else is generated or FFI-bound. Business logic, CRDT merge, and reconnection logic live in exactly one place.
| SDK | Pattern |
|---|---|
| Rust | Hand-written (frf-sdk-rust) |
| Go, C#, browser-TS | Generated from frozen proto |
| Swift, Kotlin | UniFFI over frf-ffi |
| Dart / Flutter | uniffi-bindgen-dart over the same UniFFI surface (ADR-003) |
| entity-management | Thin RealtimeAdapter on TS SDK |
Java-for-Android consumes the UniFFI Kotlin binding — do not hand-write a separate Java SDK.
| File | Description |
|---|---|
docs/IMPLEMENTATION-PLAN.md |
RFC-FRF-002 — authoritative phase-by-phase build plan |
docs/PROMETHEUS-BASE-RULES.md |
Rules 1–40 for all agents |
docs/ENVIRONMENT.md |
Environment-variable reference (required/secret/dev-only) |
docs/RUNBOOK.md |
Deployment & operations runbook (topology, secrets, CDC, scaling) |
docs/SECURITY.md |
Security model (auth boundary, tenant isolation, Keto/Cedar) |
.env.example |
Environment template — copy to .env (gitignored) |
docs/decisions/ |
Architecture Decision Records (ADRs) |
CLAUDE.md |
Project-specific agent constraints (extends base rules) |
.kbd-orchestrator/ |
KBD orchestration state — travels with the repo |
openspec/ |
OpenSpec change proposals and archive |
MIT (workspace default). Confirm before first publish.