ADR-033: Kernel-Shell Architecture

Status: Proposed
Version: 1.0
Date: 2025-12-28
Supersedes: N/A
Related ADRs: ADR-030 (VibesPro™ Foundation), ADR-030 (VibesPro™ Integration), ADR-031 (GovernedSpeed™)
Related PRDs: PRD-023

Context

SEA™ originated from VibesPro™, which itself prototyped many governance patterns. GovernedSpeed™ served as an early prototype for SEA™’s runtime governance. As these projects evolved, clear questions emerged:

How should SEA™ integrate VibesPro™ (as blackbox service vs internal module)?
How should GovernedSpeed™ code be absorbed into SEA™?
How should external UIs (Zed IDE, LibreChat) connect to SEA™?

The alternatives are:

Topology A (Nx lib): VibesPro™ as internal library with direct function calls
Topology B (Sidecar): VibesPro™ as separate process on localhost
Topology C (Service): VibesPro™ as independent deployable service
Topology D (Microfrontend): UI embedding patterns

Decision

We adopt the “One Kernel, Multiple Shells” architecture:

Kernel = SEA™ core (libs/sea/*) containing stable domain, use-cases, ports
Shells = Different runtimes/hosts that talk to the kernel (CLI, API, workers, Zed extension, LibreChat)

Integration Topology

Component	Topology	Integration	Boundary
VibesPro™	A (internal module)	Dissolved into workspace as own bounded context	`libs/vibespro/*` + `libs/vibespro/public-api`
GovernedSpeed™	Donor	Valuable pieces extracted into `libs/sea/*`	N/A (merged)
Zed IDE	D (blackbox UI)	HTTP/gRPC + LSP	Network contract
LibreChat	D (blackbox UI)	OpenAI-compatible API facade	Network contract

Concrete Nx Layout

libs/
├── sea/                          # SEA™ Kernel
│   ├── domain/                   # Pure domain: types, invariants, rules
│   ├── app/                      # Use-cases, orchestration
│   ├── ports/                    # Interfaces: repos, llm, fs, events, auth
│   └── adapters/                 # Implementations: http, db, queue, file
│
├── vibespro/                     # VibesPro™ Bounded Context
│   ├── domain/                   # VibesPro™ entities/value objects
│   ├── app/                      # VibesPro™ use-cases
│   ├── ports/                    # VibesPro™ interfaces
│   ├── adapters/                 # VibesPro™ implementations
│   └── public-api/               # ONLY thing SEA™ can import
│
apps/
├── sea-api/                      # SEA™ HTTP API shell
├── sea-worker/                   # SEA™ background worker shell
├── sea-cli/                      # SEA™ CLI shell
├── vibespro-api/                 # VibesPro™ standalone API
├── vibespro-cli/                 # VibesPro™ standalone CLI
└── vibespro-worker/              # VibesPro™ worker

Where GovernedSpeed™ Fits

GovernedSpeed™ was a prototype for SEA™, so it follows the donor pattern:

Extract valuable domain/use-case pieces into libs/sea/*
Keep only a minimal wrapper app if a runnable demo is needed
No separate bounded context (fully absorbed)

UI Integration: Zed IDE and LibreChat

Both are blackbox UI shells that talk to SEA™ over stable APIs:

UI	Integration Pattern	SEA™ Exposes
Zed IDE	LSP server + HTTP/gRPC endpoints	Editor-native actions (generate, refactor, validate)
LibreChat	OpenAI-compatible `/v1/chat/completions`	Chat-first interface via thin adapter

Rule: UI stays blackbox, SEA™ kernel stays authoritative.

Rationale

Seamless Integration: Direct function calls are fast and testable (no network boundary)
Preserved Standalone: VibesPro™ remains independently runnable via thin app wrappers
No Duplicate Rewrites: Reuse existing code rather than rewriting for separate service
Boundary Discipline: Nx tags prevent accidental coupling
Upgrade Path: Can later extract VibesPro™ to separate service by swapping adapters

Constraints

MUST

MUST keep VibesPro™ as its own bounded context with scope:vibespro tag
MUST expose VibesPro™ integration only through libs/vibespro/public-api
MUST enforce Nx module boundary rules from day 1 (see ADR-034)
MUST keep kernel (libs/sea/*) runnable without any shell
MUST support both in-process and HTTP adapters for VibesPro™ capability

MUST NOT

MUST NOT allow SEA™ to import libs/vibespro/domain/* directly
MUST NOT merge VibesPro™ domain concepts into SEA™ domain (separate ownership)
MUST NOT allow shells to contain domain logic (shells are composition + config only)
MUST NOT share persistence layer between SEA™ and VibesPro™ databases

Isomorphic Guarantees

Spec Concept	Implementation Target	Mapping Rule
Kernel libs	`libs/sea/*` structure	1:1 layer mapping
Bounded Context	`libs/vibespro/*`	Complete DDD layer structure
Public API	Port interface	Method signatures preserved
Shell	`apps/*`	Composition root only

System Invariants

INV-ID	Invariant	Type	Enforcement
INV-030	Kernel is runnable without shells	System	Unit tests on libs only
INV-031	VibesPro™ remains independently deployable	System	CI builds vibespro-api separately
INV-032	No cross-domain imports except via public-api	Structural	Nx boundary linting
INV-033	UI shells are stateless clients	System	API-only integration

Quality Attributes

Attribute	Target	Rationale
Modularity	5+ bounded contexts supported	Platform scalability
Testability	100% domain logic unit testable	No infra in domain layer
Flexibility	Swap in-process ↔ HTTP with single adapter change	Deployment options
Independence	Each BC can have own release cadence	Team autonomy

Bounded Contexts Impacted

SEA™ Kernel: Becomes the authoritative core
VibesPro™: Retains bounded context identity within workspace
Developer Tooling: Must respect boundary rules
All UI Integrations: Treated as external clients

Consequences

Positive

Unified codebase with clear boundaries
VibesPro™ can still be deployed standalone
Fast local development (no service discovery)
Clear upgrade path to microservices if needed

Negative

More discipline required to maintain boundaries
Nx tag management overhead
Potential for boundary erosion if not enforced

Mitigations

ADR-034 defines strict Nx boundary enforcement
CI fails on illegal imports
Regular dependency graph reviews

Observable Success

You can:

Delete all apps/* and still have fully working kernel in libs/sea/*
Run VibesPro™ standalone without any SEA™ UI
Point LibreChat at SEA™ and chat works without forking LibreChat
Add Zed extension that calls SEA™ endpoints for editor actions