How modules work in the Insolitum Universe platform. Iframe-based plugin architecture, authentication flow, and data access patterns.

Module Architecture

Insolitum Universe uses an iframe-based plugin architecture. Each module is an independent web application embedded inside the Universe Shell.

Module Architecture — Click any component for details

Core Concepts

Universe Shell

The main application (universe-shell) provides:

Authentication — Supabase Auth with JWT tokens
Navigation — Sidebar, routing, module switching
Module loading — Iframe embedding with dynamic routes
Subscription management — Module access control per organization

Partner Modules

Your module is an independent Next.js 14 application that:

Runs on its own domain/port (e.g., my-module.vercel.app)
Is embedded in the Shell via <iframe>
Receives authentication via postMessage protocol
Accesses the shared Supabase database with tenant isolation
Communicates with other modules via NATS events

Shared Infrastructure

Component	Description
Supabase	PostgreSQL database + Auth + Realtime. Shared across all modules. Row Level Security (RLS) ensures tenant isolation.
NATS	Distributed event bus for real-time communication. Modules publish/subscribe via WebSocket gateway.
WebSocket Gateway	Socket.io server that bridges browser clients to NATS. Handles auth and tenant routing.

How Shell Loads Your Module

User navigates to /admin/modules/your-module in the Shell
Shell checks module_subscriptions table — does this org have access?
Shell renders <ModuleFrame> component with your deploy_url
An <iframe> loads your module's URL with ?org_id=<uuid> parameter
Your module mounts and sends REQUEST_AUTH_SESSION to parent
Shell responds with AUTH_SESSION containing access/refresh tokens
Your module's ShellAuthProvider sets the Supabase session
Your module is now fully authenticated and renders its UI

Built-in vs Partner Modules

Aspect	Built-in Modules	Partner Modules
Routing	Hardcoded routes in Shell	Dynamic catch-all route `/admin/modules/:slug/*`
Config	`MODULE_CONFIGS` in `@insolitum/types`	`modules` table in Supabase
Examples	LexShift, NeuroSense, Fabrica	Your custom modules
Deploy	Same monorepo	Separate repository, own hosting

Data Flow

┌─────────────────────────────────────────────────────┐
│                   Universe Shell                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │               Your Module (iframe)               │ │
│  │                                                   │ │
│  │  useShellAuth() ──→ Supabase queries (RLS)       │ │
│  │  useModuleApi() ──→ Tenant-scoped CRUD           │ │
│  │  useNats()      ──→ WebSocket ──→ NATS events    │ │
│  │                                                   │ │
│  └─────────────────────────────────────────────────┘ │
│                                                       │
│  postMessage ←──→ AUTH_SESSION (tokens)              │
└─────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
    ┌──────────┐                ┌──────────────┐
    │ Supabase │                │ NATS Cluster │
    │ (shared) │                │  (events)    │
    └──────────┘                └──────────────┘

Directory Structure Convention

Every module follows the Next.js 14 App Router pattern:

my-module/
├── src/
│   ├── app/                    # Pages and API routes
│   │   ├── layout.tsx          # ShellAuthProvider wrapper
│   │   ├── page.tsx            # Main page / dashboard
│   │   ├── [feature]/page.tsx  # Feature pages
│   │   └── api/
│   │       └── health/route.ts # Health endpoint (required!)
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utilities
│   ├── components/             # React components
│   └── i18n/                   # Internationalization
├── package.json
├── next.config.ts              # CSP headers for iframe
├── tailwind.config.ts          # Dark theme
└── .env.local                  # Credentials

The next.config.ts must include CSP headers that allow iframe embedding from *.insolitum.ai. The module-starter template includes this configuration by default.

Next Steps

Module Lifecycle — Initialization, auth, and shutdown
Authentication — Deep dive into postMessage protocol
Database — Multi-tenant data access

Module Architecture

Module Architecture — Click any component for details

On this page