Self-Contained Systems (SCS)
The VENI-AI platform is built on the Self-Contained Systems (SCS) architectural pattern. Unlike traditional microservices that often focus only on the backend, an SCS is an autonomous web application that includes its own user interface, business logic, and data storage.
💎 Core Philosophy
The primary goal of SCS is decoupling. Most platforms impose horizontal layers where a single feature requires coordination across UI, Backend, and Database teams. In VENI-AI, we use vertical slices:
- Autonomy: Each satellite module can be developed, tested, and deployed without affecting others.
- Ownership: One team owns the entire stack of a feature, from the database schema to the UI components.
- Resilience: A failure in one satellite (e.g., HRM) does not bring down another (e.g., Drive).
🏗️ The Three Pillars of a Satellite
Every satellite in the VENI-AI ecosystem must fulfill three requirements to be considered a valid SCS:
1. Own User Interface (Federated UI)
Satellites do not just provide APIs; they provide pages. Using Module Federation, the Shell loads the satellite's UI at runtime.
- Standalone Mode: Each UI can run independently on its own port (e.g.,
:4175). - Integrated Mode: The Shell mounts the remote UI into its main content area, providing seamless navigation.
2. Own Business Logic (Independent API)
Each satellite runs its own API server (standardized on Bun + Hono + Ignis v2).
- Service Scoping: The satellite issues its own JWTs scoped specifically to its domain.
- Contract-First: Inter-service communication happens via gRPC (Connect) or REST, never via direct database access.
3. Own Data (Isolated Storage)
Each satellite owns its database schema.
- No Shared Tables: No satellite is allowed to read or write to another's database.
- Migration Autonomy: Satellites manage their own Drizzle migrations, allowing them to evolve their data models at their own pace.
🔗 The Shell Integration
If satellites are independent, the Shell acts as the glue that binds them into a single enterprise experience:
- Identity Hub: The Shell handles Keycloak authentication and broadcasts the RSA-signed JWT to all satellites.
- App Registry: A dynamic directory that tells the Shell which satellites are available and where their entry points are.
- Navigation & Layout: Standardized headers, sidebars, and user menus that make 50 independent satellites feel like one unified app.
- Universal Audit: A centralized service where satellites report critical business events.
🚀 Comparison: Monolith vs. SCS
| Feature | Legacy Monolith | VENI-AI (SCS) |
|---|---|---|
| Deployment | "Big Bang" (All or nothing) | Granular (Service by service) |
| Database | Massive Shared DB | Isolated per module |
| UI | Tightly coupled templates | Federated Micro-frontends |
| Team Velocity | Blocked by cross-team dependencies | Parallel independent work |
| Failure Impact | Global downtime | Isolated service degradation |
🛠️ Implementation Standards
When building a new SCS on VENI-AI, we adhere to the following stack:
- Backend: Ignis v2 Framework (Bun/Hono)
- Database: PostgreSQL with Drizzle ORM
- Frontend: React + Vite + Tailwind CSS
- Communication: Module Federation (UI) & Connect RPC (gRPC)