System Overview
The Event-Driven Spine
The heart of the platform is not a database or an application server — it is an immutable, permanent spine consisting of an Event Bus and a Work System. Everything else hangs off this spine.
┌─────────────────────────────────────────────────────────┐
│ PLUGIN LAYER │
│ Connector Plugins Channel Plugins Rule Operators │
└────────────────────────┬────────────────────────────────┘
│ events
┌────────────────────────▼────────────────────────────────┐
│ EVENT BUS (NATS JetStream) │
│ Immutable event stream — all state changes │
└──┬──────────────────────────────────────────────────┬───┘
│ enqueues jobs │ subscribes
┌──▼────────────────────┐ ┌──────────────────▼───┐
│ JOB QUEUE (pg-boss) │ │ SERVICE MODULES │
│ realtime │ │ │
│ interactive │ │ ETL Service │
│ background │ │ Rules Service │
└──┬────────────────────┘ │ Policy Service │
│ dispatches │ Search Service │
┌──▼────────────────────┐ │ AI Service │
│ WORKERS │ └──────────────────────┘
│ (job handlers) │
└───────────────────────┘
│ reads/writes
┌────────────────────────▼────────────────────────────────┐
│ DATA LAYER │
│ PostgreSQL + pgvector Meilisearch NATS (event log) │
└─────────────────────────────────────────────────────────┘
│ API
┌────────────────────────▼────────────────────────────────┐
│ SOVEREIGN API (Fastify) │
│ REST endpoints Webhook receivers /device-events │
└──────────────┬──────────────────────────────────────────┘
│
┌──────────┴──────────┐
│ │
┌───▼────┐ ┌──────▼────────┐
│ Web │ │ Android/Win │
│ App │ │ Client + Sensor│
└────────┘ └───────────────┘
All Services
| Service | Responsibility |
|---|---|
| Plugin Manager | Plugin lifecycle, loading, V8 sandboxing, health monitoring |
| Connector Service | Manages connector plugins, schedules syncs, receives webhook data |
| Communication Service | Manages channel plugins, routes inbound/outbound messages and calls |
| ETL Service | Transforms raw connector data → unified entity model |
| Data Service | Knowledge graph CRUD — all reads/writes to PostgreSQL |
| Search Service | Indexes entities in Meilisearch; handles full-text queries |
| Rules Service | Evaluates rules against events; fires actions |
| Policy Service | Access control, consent management, immutable audit log |
| Job Queue | pg-boss — durable, prioritized job execution (BullMQ planned for high-throughput path; not yet a hub dependency) |
| Event Bus | NATS JetStream — pub/sub + persistent event store |
| AI Service | LLM orchestration (OpenRouter), RAG engine, Workflow Engine |
| Stream Processing | Real-time state updates to Redis (Present temporal plane) |
| Intentions Service | Future temporal plane — goals, tasks, scheduled triggers |
| Federation Service | ActivityPub server — federated social, marketplace, governance |
Architectural Principles
1. Data First, Actions Second Every external integration lands data in the unified model before anything acts on it. The Design Law:
Every integration must first land as data in the unified model, not as a new action. Actions are consumers of data, never the source of truth.
2. Event-Driven Core All significant state changes are published as immutable events. Services communicate through the event bus, never by calling each other's APIs directly or accessing each other's databases.
3. Plugin-First Extensibility Every external integration is a sandboxed plugin with a declared manifest. New capabilities are added via plugins, not by modifying core services.
4. Service Isolation Services never access each other's databases. A service that needs data from another service subscribes to its events or calls the Sovereign API.
5. Zero-Trust by Default The Policy Service is the enforcement point for all data access. Every service, plugin, and application must be authorized before touching any data. Every access is logged.
6. Idempotent Jobs Every job handler must be safe to retry. The event ID that triggered a job serves as the idempotency key.
Data Flow: Inbound (Connector → Storage)
External Service (e.g., MS Graph)
│
▼
Connector Plugin (ms-graph)
│ raw data
▼
Connector Service ──publishes──► connector.DataReceived (NATS)
│
▼
Job Queue
ProcessIncomingDataJob (background)
│
▼
ETL Service
(clean, normalize, enrich)
│ entities
▼
Data Service ──writes──► PostgreSQL
│ publishes
▼
data.EntityCreated (NATS)
│
┌─────────┴─────────┐
▼ ▼
Search Service Rules Service
(index in Meili) (evaluate rules)
Data Flow: Inbound Call (Twilio → Rules → Action)
Partner's phone call
│
▼
Twilio webhook → Communication Service → communication.CallStarted (NATS)
│
▼
Rules Service
(evaluates all enabled rules)
│
Rule matches:
caller = "Partner" AND
location = "Work"
│
▼
SendOutgoingMessageJob
(interactive queue)
│
▼
Communication Service
→ Twilio Channel Plugin
→ SMS sent to caller