Platform Architecture

VENI-AI is an Agentic Enterprise OS designed as a federation of Self-Contained Systems (SCS). It moves away from monolithic or horizontally layered architectures in favor of independent, vertically-integrated services coordinated by a central Shell.

---

1. The Shell-and-Satellite Model

The platform is structured into two distinct roles:

The Shell (The Orchestrator)

The Shell is the single integration point and the "Entry Hub" for the entire platform. It owns:

• Global Identity: Keycloak integration and RSA-signed SSO.
• Service Registry: A dynamic catalog of available applications.
• Unified Navigation: The Launchpad and global sidebar.
• Enterprise Governance: B2B onboarding, billing, and global RBAC policies.

Satellites (The Domain Owners)

Satellites are independent applications (e.g., Drive, HRM, Documents) that own a specific business domain. Following the SCS philosophy, each satellite is a complete stack:

• Independent UI: Loaded into the Shell via Module Federation.
• Independent Logic: Its own API, business rules, and background jobs.
• Independent Data: Its own isolated database schema.

---

2. Self-Contained Systems (SCS)

Unlike microservices that often share databases or UIs, a VENI-AI Satellite is fully autonomous.

☸ Kubernetes Cluster

Shell SCS — The Orchestrator

Shell UI

Keycloak · SSO · Launchpad

→

Shell API

UserSvc · OrgSvc · RBAC

→

Shell DB

PostgreSQL

↙ Module Federation

Module Federation ↘

↓

↓

Drive SCS

Drive UI

Module Federation Remote

↓

Drive API

DriveSvc · FileSvc

↓

Drive DB

PostgreSQL

EventSubscriberService
group: drive-api

HRM SCS

HRM UI

Module Federation Remote

↓

HRM API

EmployeeSvc · LeaveSvc

↓

HRM DB

PostgreSQL

EventSubscriberService
group: hrm-api

XREADGROUP (stream:users)

XREADGROUP (stream:users + stream:organizations)

↓

← XADD →

↓

Platform Event Bus · Redis Streams

not owned by any SCS

shell:stream:users

user.created
user.updated
user.deleted

shell:stream:organizations

org.created
org.updated
org.deleted

---

3. Identity & Authentication Architecture

VENI-AI uses a Hybrid Token Exchange model to ensure security without tight coupling.

1. Identity Hub: Users authenticate with the Shell (via Keycloak).
2. RSA Signing: The Shell issues an RS256 JWT signed with its private key.
3. Public JWKS: The Shell exposes its public keys at /.well-known/jwks.json.
4. Satellite Exchange: When a user accesses a Satellite, the Satellite API verifies the Shell JWT against the JWKS and issues a Service-Scoped JWT.
5. Isolation: All subsequent calls to the Satellite API use the scoped token, ensuring one service cannot impersonate another.

---

4. Integration Patterns

Module Federation (UI)

Remotes are loaded at runtime. The Shell queries the App Registry to find the remoteEntry.js URL for each app and injects it into the workspace.

Event-Driven Architecture / Redis Streams (Async Data Sync)

The Shell is the single source of truth for users and organizations. Instead of satellites calling Shell synchronously, Shell publishes domain events to a Platform Event Bus (Redis Streams). Each SCS consumes independently from its own consumer group.

SCS principle: Redis Streams is platform-level infrastructure — like a load balancer or service mesh. It is not owned by Shell or any satellite. Each SCS connects to the bus independently; no SCS application data or business logic is shared.

• Drive SCS — subscribes to shell:stream:users only (stores shell_user_id locally)
• HRM SCS — subscribes to shell:stream:users + shell:stream:organizations (stores ref_id locally)

Each satellite maintains its own local read model in its own isolated DB. Once synced, it never needs to call Shell to resolve user or org data.

→ See Event-Driven Architecture for the full reference.

Connect / gRPC (Internal)

For high-performance server-to-server communication (e.g., the Shell checking a Satellite's health or syncing permissions), the platform uses Connect RPC (Protobuf over HTTP/2).

REST & Zod (External)

All public-facing APIs are standard RESTful services, using Zod for strict contract enforcement and TypeScript safety from the DB to the UI.

---

5. Implementation Framework: Ignis v2

While the architecture is platform-level, we use the Ignis v2 framework to implement these patterns consistently.

• Dependency Injection: Decouples business logic from infrastructure.
• Base Controllers/Services: Provides standard patterns for health checks, logging, and error handling.
• Drizzle ORM: Ensures type-safe, version-controlled database migrations for every SCS.

Next Steps

• Data & Persistence — Learn how SCS data is managed.
• Identity & Security — Deep dive into the RSA handshake.
• Event-Driven Architecture — Redis Streams pub/sub between Shell and satellites.
• Create Remote App — Build your first Satellite.