Unified Module Specification: Shell
The Shell is the central nervous system of the VENI-AI platform. It provides the core infrastructure for identity, multi-tenancy, navigation, and service orchestration, abstracting these complexities away from satellite modules.
v1.0 — ApprovedPlatform: VENI-AI CoreDomain: Identity & Governance
1. Module Overview
The Shell module is designed to provide a "Single Source of Truth" for identity and governance. Its primary goal is to provide a seamless Single Sign-On (SSO) experience across all Self-Contained Systems (SCS) while maintaining strict data isolation between organizations.
- Primary Goal: Centralize identity, authorization, and tenant management.
- Secondary Goal: Orchestrate the micro-frontend launchpad and service discovery.
2. Specification Navigation
This specification is divided into technical, data, and functional domains:
| Section | Focus | Audience |
|---|---|---|
| Technical Specification | Architecture, Stack, Security | Developers, DevOps |
| Database Schema | Tables, ERDs, Types | Developers, DBAs |
| API Reference | REST Endpoints, Contracts | Integrators, Frontend Devs |
| Functional Requirements | Features, REQ IDs | BAs, Testers |
3. Functional Requirements (SRS)
3.1 Identity & SSO (AUTH)
- REQ-SH-001: System MUST support multi-provider authentication (Local, Keycloak/OIDC, Google).
- REQ-SH-002: System MUST issue platform-wide RS256 JWTs for session management.
- REQ-SH-003: System MUST provide a secure Token Exchange mechanism for satellite modules.
3.2 Tenant Management (TENANT)
- REQ-SH-004: System MUST strictly isolate all data by
organizationId. - REQ-SH-005: System MUST support Auto-provisioning of organizations based on email domains.
- REQ-SH-006: System MUST allow organization admins to manage users and roles (States:
ACTIVE,INACTIVE,SUSPENDED).
3.3 Service Launchpad (APPS)
- REQ-SH-007: System MUST provide a centralized Launchpad for navigating between remote apps.
- REQ-SH-008: System MUST perform Service Discovery to identify active satellite modules (Status:
AVAILABLE).
3.4 Governance & Billing (GOV)
- REQ-SH-009: System MUST implement Casbin-based RBAC for platform-wide permissions.
- REQ-SH-010: System MUST track usage and enforce Plan Quotas (Hobby, Pro, Enterprise) via Stripe integration.
4. Feature Specifications (Deep Dives)
Detailed specifications for each core feature:
- Identity & SSO
- Service Launchpad
- RBAC & Permissions
- Org & User Mgmt
- Billing & Quotas
- Audit & Compliance
- Service Orchestration
5. Non-Functional Requirements (NFR)
5.1 Performance
- NFR-SH-PER-001: Authentication validation (local) MUST complete in < 50ms.
- NFR-SH-PER-002: Launchpad load time MUST be < 800ms.
5.2 Security & Compliance
- NFR-SH-SEC-001: Data leakage between tenants is a Severity-0 violation.
- NFR-SH-SEC-002: All sensitive platform secrets MUST be stored in a secure Vault.
- NFR-SH-SEC-003: Audit logs MUST be immutable and captured for all security events.