Technical Specification: Shell
This document details the technical architecture, technology stack, and integration patterns for the Shell, the central orchestration hub of the VENI-AI platform.
1. High-Level Architecture
The Shell operates as the Container (Host) in a Micro-frontend (MFE) architecture and the Identity Provider (IdP) in a Self-Contained Systems (SCS) ecosystem.
Component Diagram
2. Technology Stack
Backend (API)
- Runtime: Bun (v1.0+)
- Framework: Ignis Framework + Hono
- ORM: Drizzle ORM
- Database: PostgreSQL 15+
- Security: Casbin (RBAC) + Keycloak (OIDC)
- S2S Comm: Connect Protocol (gRPC-compatible)
Frontend (UI)
- Library: React 18+ with TypeScript
- Bundler: Vite with Module Federation
- UI Kit: ARDOR (Tailwind CSS v4 + Radix UI)
- Icons: Lucide React
3. Core Implementation Logic
3.1 Unified Module Entry (ShellEntry)
Every remote application MUST expose a ./ShellEntry via Module Federation. This entry point allows the Shell to dynamically mount and unmount applications without page reloads.
// Remote App ShellEntry Pattern
export const mount = (container: HTMLElement) => {
const root = createRoot(container);
root.render(<App />);
return () => root.unmount();
};3.2 Hybrid Token Authentication
The Shell issues a platform-wide RS256 JWT. Remote services can:
- Verify Locally: Using the Shell's JWKS endpoint (
/.well-known/jwks.json). - Exchange: Call
/auth/exchangeto get a service-specific short-lived token with scoped audience.
3.3 Casbin RBAC Integration
Authorization is managed via Casbin policies stored in the Shell database.
- Policies: Defined as
p, sub, obj, act(e.g.,p, role:admin, drive:files, write). - Enforcement: Decorators like
@authorize()in the backend ensure zero-trust access.
4. Integration Patterns
4.1 Multi-tenant Isolation
The Shell enforces tenant isolation at the database level using a mandatory org_id column on all tenant-specific tables. The Shell API automatically injects this filter into queries based on the authenticated user's session.
4.2 Service Discovery
The Shell maintains a registry of active satellite modules. Upon loading, the Shell UI fetches this registry to populate the navigation sidebar and the application launchpad.
5. Security & Governance
- Encryption: All cross-service communication (S2S) is encrypted via TLS.
- Audit Logging: Every platform-level change (user invite, role change, organization update) is recorded in an immutable audit trail.
- Credential Protection: The Shell never stores plain-text passwords; it delegates sensitive identity storage to Keycloak or uses Argon2 hashing for local accounts.
Related Links