Core Module Requirements

This document defines the core requirements and specifications for building modules on the BusinessOS platform. All modules—whether built internally or by third-party developers—must adhere to these requirements to ensure compatibility, security, and a consistent user experience.

Table of Contents

1. Overview
2. Module Structure
3. Required Interfaces
4. Metadata Specification
5. Template Compatibility
6. Database Migrations
7. API Routes
8. Permissions System
9. Navigation & UI
10. Lifecycle Hooks
11. Landing Page Integration
12. Module Registration
13. Security Requirements
14. Best Practices
15. Example Module

---

Overview

Modules are the building blocks of BusinessOS functionality. Each module is a self-contained unit that can provide:

• UI Components: Pages and navigation items
• API Routes: Backend endpoints for data operations
• Database Tables: Via migrations with Row-Level Security (RLS)
• Permissions: Granular access control
• Events: For automation and integration
• Public Site Content: Landing page sections for project sites

Key Principles

1. Isolation: Modules must not directly access other modules' data
2. Multi-tenancy: All data must be tenant-scoped with RLS
3. Declarative: Configuration over code where possible
4. Versioned: Semantic versioning for compatibility tracking

Two-layer Architecture (Required)

Every module must be designed with a strict separation of operational layers:

• Project Owner / Admin (Backoffice Layer): where builders configure and operate the module inside a specific project.

  • Injects navigation into the project sidebar under Project Modules when installed.
  • Provides project-scoped admin pages (settings, data management, analytics, publishing, pricing, access rules).
  • Provides project-scoped admin APIs (used by those pages).

• End User / Public (Frontend Layer): where end-users consume what the project owner publishes on the project site.

  • May expose public pages (e.g. browse courses) and/or authenticated end-user pages (e.g. portal/workspace routes).
  • Must never expose backoffice functionality.

Architectural rule: modules are infrastructure attached to a project. Project owners configure and deploy; end users consume.

Payments Core Rule (Required)

Payments Core is the single billing authority of the platform.

Any module that requires payments, subscriptions, or monetization must integrate exclusively with the payments-core module for:

• Checkout/session creation
• Subscription state
• Payment events (success/failure)
• Entitlements (grant/revoke)
• Billing settings and reporting

Strict prohibition: direct integrations with Stripe (or any payment provider) inside feature modules are not allowed.
Feature modules may define what requires payment, but must delegate how billing works to Payments Core.

Core Module Experience (Required)

Each project may select exactly one installed module as its core module. The core module drives the default end-user experience and ensures the project site feels like a cohesive product rather than disconnected features.

• Storage: project_module_installations.config.isCoreModule = true (only one installation per project may have this flag).
• Impacts the end-user site:
  • Landing (/): chooses an industry-appropriate template based on coreModuleId (e.g. Courses vs Digital Products).
  • Site shell layout: the global header is shared; core module may influence whether the site uses header-only vs header+sidebar patterns.
  • Authenticated home: post-login area is template/module route-driven (for example /portal, /courses, /products).
• Module responsibility:
  • Provide siteNavigation items for the header (and set requiresAuth when needed).
  • Provide sitePages for public entry points (catalog/detail/learning/downloads), but do not render their own headers.

---

Module Structure

Every module must follow this directory structure:

modules/
└── {module-name}/
    ├── package.json          # Module package definition
    ├── tsconfig.json         # TypeScript configuration
    └── src/
        ├── index.ts          # Module definition & registration
        ├── project/          # Project-owner (backoffice) layer
        │   ├── api/          # Project-scoped admin API handlers
        │   │   └── *.ts
        │   └── pages/        # Project admin pages (rendered under /p/:slug/modules/:moduleId)
        │       └── *.tsx
        ├── site/             # End-user/public layer (optional)
        │   └── pages/        # Public site pages (rendered under /site/* via module router)
        │       └── *.tsx
        ├── api/              # (Legacy/optional) tenant-level module API handlers
        │   └── *.ts
        ├── pages/            # (Legacy/optional) tenant-level pages (avoid for new modules)
        │   └── *.tsx
        └── components/       # Reusable components
            └── *.tsx

package.json

{
  "name": "@v2/module-{name}",
  "version": "1.0.0",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "dependencies": {
    "@v2/modules": "workspace:*",
    "@v2/database": "workspace:*"
  },
  "devDependencies": {
    "@v2/tsconfig": "workspace:*",
    "typescript": "^5.0.0"
  }
}

tsconfig.json

{
  "extends": "@v2/tsconfig/react-library.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

---

Required Interfaces

All modules must implement the ModuleDefinition interface:

interface ModuleDefinition {
  // REQUIRED
  metadata: ModuleMetadata;
  
  // OPTIONAL
  // -----------------------------
  // Project-owner (backoffice)
  // -----------------------------
  projectAdminNavigation?: ModuleNavItem[];
  projectAdminPages?: Record<string, ModuleRenderable<ModulePageProps>>;
  projectAdminApiRoutes?: ModuleApiRoute[];
  projectSettingsPage?: ModuleRenderable<ModulePageProps>;

  // -----------------------------
  // End-user/public (site)
  // -----------------------------
  sitePages?: Record<string, ModuleRenderable<SiteModulePageProps>>;
  siteApiRoutes?: SiteModuleApiRoute[]; // authenticated end-user APIs under /api/site/modules/{moduleId}
  siteNavigation?: SiteNavItem[];       // end-user site header navigation items

  // -----------------------------
  // Legacy (avoid for new modules)
  // -----------------------------
  navigation?: ModuleNavItem[];          // tenant-level nav (not project-scoped)
  apiRoutes?: ModuleApiRoute[];          // tenant-level APIs under /api/modules/{moduleId}
  permissions?: ModulePermission[];
  migrations?: ModuleMigration[];
  pages?: Record<string, ModuleRenderable<ModulePageProps>>;
  settingsPage?: ModuleRenderable<ModulePageProps>;
  dashboardWidget?: ComponentType<{ context: ModuleContext }>; // legacy tenant-level widget (deprecated)
  onEnable?: (tenantId: string) => Promise<void>;
  onDisable?: (tenantId: string) => Promise<void>;
}

Routing Conventions

• Project backoffice pages: /p/:projectSlug/modules/:moduleId/...
• Project backoffice APIs: /api/projects/:projectId/modules/:moduleId/...
• Public site pages: exposed by module sitePages, routed under the project host and rewritten to /site/... internally
• End-user APIs: /api/site/modules/:moduleId/... (when using siteApiRoutes)

---

Metadata Specification

The metadata object is required and describes your module:

Required Fields

Optional Fields

Category Types

type ModuleCategoryType = 
  | 'foundation'   // Core functionality (team, auth)
  | 'operations'   // Business operations (tasks, projects)
  | 'sales'        // Sales & CRM
  | 'marketing'    // Marketing tools
  | 'finance'      // Invoicing, payments
  | 'automation'   // Workflows, integrations
  | 'analytics'    // Reporting, dashboards
  | 'ai'           // AI-powered features
  | 'developer'    // Developer tools
  | 'enterprise';  // Enterprise features

---

Template Compatibility

Modules must explicitly declare the end-user site capabilities they require so template compatibility can be enforced at runtime.

Required metadata field

Use:

metadata: {
  // ...
  requiredSiteCapabilities: [
    'layout.publicHeader',
    'layout.workspaceContent',
    'ui.navigation.moduleLinks',
    'ui.surface.card',
    'ui.form.controls',
    'ui.feedback.error',
    'ui.data.list',
    'ui.data.keyValue',
  ],
}

Source of truth

• Type: ModuleSiteThemeCapability
• Constant: MODULE_SITE_THEME_CAPABILITIES
• Package: @v2/modules

Enforcement

• Unknown capability IDs are rejected during registerModule()
• Module install is blocked if the current project template does not satisfy requiredSiteCapabilities
• Project template switch is blocked if installed modules require missing capabilities
• Core-module changes are blocked when they produce missing capability coverage

---

Database Migrations

Modules can create database tables via migrations. All tables MUST implement Row-Level Security (RLS).

Migration Structure

interface ModuleMigration {
  name: string;   // Unique name: '0001_create_contacts_table'
  up: string;     // SQL to run (up migration)
  down?: string;  // SQL to run (down migration) - optional
}

Required RLS Pattern

Every table created by a module MUST follow this pattern:

-- 1. Create table with tenant_id
CREATE TABLE IF NOT EXISTS {module}_table (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
  -- ... other columns
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- 2. Create indexes
CREATE INDEX IF NOT EXISTS idx_{module}_table_tenant 
  ON {module}_table(tenant_id);

-- 3. Enable RLS
ALTER TABLE {module}_table ENABLE ROW LEVEL SECURITY;
ALTER TABLE {module}_table FORCE ROW LEVEL SECURITY;

-- 4. Create RLS policies using current_tenant_id()
CREATE POLICY {module}_table_select ON {module}_table
  FOR SELECT USING (tenant_id = current_tenant_id());
CREATE POLICY {module}_table_insert ON {module}_table
  FOR INSERT WITH CHECK (tenant_id = current_tenant_id());
CREATE POLICY {module}_table_update ON {module}_table
  FOR UPDATE USING (tenant_id = current_tenant_id());
CREATE POLICY {module}_table_delete ON {module}_table
  FOR DELETE USING (tenant_id = current_tenant_id());

-- 5. Grant permissions to app_user role
GRANT SELECT, INSERT, UPDATE, DELETE ON {module}_table TO app_user;

Project-Scoped Tables

For tables scoped to projects (not tenants), use this pattern:

CREATE TABLE IF NOT EXISTS {module}_table (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
  -- ... other columns
);

-- RLS via project's tenant
CREATE POLICY {module}_table_select ON {module}_table
  FOR SELECT USING (
    project_id IN (
      SELECT id FROM projects WHERE tenant_id = current_tenant_id()
    )
  );

Migration Execution Flow

Important: Migrations are executed in two phases. Also note that migrations are optional — UI-only modules may have zero migrations.

Phase 1: Global Migrations (Admin Enables Module)

When a platform admin makes a module "available" in the admin panel, the module's migrations run globally:

Admin sets available=true → runGlobalModuleMigrations() → Tables created

• Tables are created with CREATE TABLE IF NOT EXISTS
• Tracked in module_schema_versions (canonical) and mirrored to platform_module_migrations for compatibility
• RLS policies are applied (data isolation is automatic)
• This happens BEFORE any user can install the module

Phase 2: User Installation (No Migration Needed)

When a user installs the module on their project:

User clicks "Install" → Module enabled for project → No migrations run

• Tables already exist from Phase 1
• User's data is automatically isolated by RLS
• Module is immediately usable

Why This Matters

Example Flow

1. Developer creates end-user-auth module with migrations
2. Admin enables module in admin panel (available=true)
   → CREATE TABLE end_users (...)
   → CREATE TABLE end_user_sessions (...)
   → Tables now exist globally
3. User A installs module on Project X
   → No migrations, just enables feature
   → User A's end users stored in end_users table
4. User B installs module on Project Y
   → No migrations, just enables feature
   → User B's end users stored in same table, isolated by RLS

---

API Routes

Modules can define three API surfaces:

• projectAdminApiRoutes (required for backoffice operations)
  • Mounted at /api/projects/{projectId}/modules/{moduleId}/{...path}
• siteApiRoutes (optional, end-user/project-site APIs)
  • Mounted at /api/site/modules/{moduleId}/{...path}
• apiRoutes (legacy tenant-level module APIs)
  • Mounted at /api/modules/{moduleId}/{...path}
  • Avoid for new module development

Site API Routes (End-User / Project Site)

Some modules also provide end-user APIs for project subdomains (e.g., myproject.credsnet.com).

These endpoints are mounted at:

/api/site/modules/{moduleId}/{...path}

Modules declare these via siteApiRoutes (distinct from backoffice projectAdminApiRoutes).

The platform will automatically:

• Resolve project context from the request host (via resolveProjectContext() pattern)
• Validate the end-user session (project_session cookie)
• Ensure the module is installed for the project

This makes it possible for modules to expose end-user data without hardcoding module logic into site pages.

Legacy Dashboard Contributions (Deprecated)

/dashboard is now a compatibility redirect in template-first projects.

If you maintain legacy projects, modules can contribute dashboard sections by adding:

• metadata.siteDashboardSections: a list of section descriptors (rendered by the platform dashboard)
• siteApiRoutes: endpoints that return user-specific section data

Important (legacy mode): modules do not render their own dashboard UI. The dashboard owns the UI; modules provide only:

• a kind hint (which renderer to use)
• an endpoint (where to fetch data)
• display metadata (title/icon/order)

interface SiteDashboardSectionDefinition {
  id: string;
  title: string;
  description?: string;
  icon?: string;     // SVG icon name
  order?: number;
  kind: 'accountSummary' | 'coursesProgressSummary' | 'productsDownloadsSummary' | 'keyValue';
  endpoint: { method?: 'GET'; path: string }; // relative to /api/site/modules/{moduleId}
  requiresAuth?: boolean;
}

Route Structure

interface ModuleApiRoute {
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  path: string;                    // Relative path, e.g., '/contacts/:id'
  handler: (request: Request, context: ModuleContext) => Promise<Response>;
  minimumRole?: 'owner' | 'admin' | 'member'; // REQUIRED in module route definitions
  permissions?: string[];          // Optional metadata (must align with minimumRole)
}

RBAC Contract (Enforced)

• Every route in projectAdminApiRoutes must explicitly set minimumRole
• Legacy apiRoutes (if still used) must also set minimumRole
• Role intent:
  • member for read/list/view endpoints
  • admin for create/update/delete/publish/configuration endpoints
  • owner only for tenant-critical controls
• Platform routers enforce role checks before invoking handlers
• Missing or invalid permission-action contracts fail closed with ROUTE_PERMISSION_CONFIG_ERROR

Handler Context

Every handler receives a ModuleContext:

interface ModuleContext {
  tenantId: string;      // Current tenant ID
  tenantSlug: string;    // Current tenant slug
  projectId?: string;    // Current project ID (if applicable)
  projectSlug?: string;  // Current project slug
  userId?: string;       // Current user ID
  userRole?: 'owner' | 'admin' | 'member';
  config: Record<string, unknown>;  // Module configuration
}

Example Handler

export async function handleGetContacts(
  request: Request,
  context: ModuleContext
): Promise<Response> {
  const { tenantId } = context;
  
  const contacts = await withTenantQuery(tenantId, (sql) => sql`
    SELECT * FROM crm_contacts ORDER BY created_at DESC
  `);
  
  return Response.json({ contacts });
}

---

Permissions System

Modules define granular permissions that integrate with the platform's RBAC system.

Important:

• Route access enforcement is driven by minimumRole on each API route.
• permissions are still valuable for capability labeling, auditing, and policy intent.
• Keep permissions aligned with route behavior, but do not use permissions alone as the only access contract.

Permission Structure

interface ModulePermission {
  id: string;          // Format: '{module}:{resource}:{action}'
  name: string;        // Human-readable name
  description: string; // What this permission allows
}

Naming Convention

Permission IDs must follow this format:

{module-id}:{resource}:{action}

Examples:

• crm:contacts:read
• crm:contacts:write
• crm:contacts:delete
• invoicing:invoices:send

Action suffix guidance (must map to known actions if route-level inference is ever used):

• read, list, view
• write, create, update, delete, publish, manage, admin, configure

Example Permissions

permissions: [
  {
    id: 'crm:contacts:read',
    name: 'View Contacts',
    description: 'Can view the list of contacts',
  },
  {
    id: 'crm:contacts:write',
    name: 'Manage Contacts',
    description: 'Can create, edit, and delete contacts',
  },
]

---

Navigation & UI

Navigation Items

Modules can add items to the application sidebar:

interface ModuleNavItem {
  label: string;           // Display text
  href: string;            // Route path
  icon?: string;           // SVG icon name (no emojis)
  permissions?: string[];  // Required permissions to see
  children?: ModuleNavItem[]; // Nested items
}

Public Site Navigation (Header)

Modules can contribute end-user navigation links for the project site header via siteNavigation.

interface SiteNavItem {
  label: string;          // Display label in the header
  href: string;           // Absolute site path (e.g. '/courses', '/products')
  icon?: string;          // SVG icon name
  requiresAuth?: boolean; // Hide unless end-user is logged in
}

Rules:

• The platform header renders navigation; module pages must not create their own headers.
• siteNavigation should point to sitePages routes (public entry points), not internal /site/* paths.

Pages

Pages are React components that receive ModulePageProps:

interface ModulePageProps {
  context: ModuleContext;
  params: Record<string, string>;
  searchParams: Record<string, string>;
}

Dashboard Widget (Deprecated)

Legacy widget contract from pre-template-first architecture:

dashboardWidget?: ComponentType<{ context: ModuleContext }>;

---

Lifecycle Hooks

Modules can define hooks that run when enabled/disabled:

// Called when module is enabled for a tenant
onEnable?: (tenantId: string) => Promise<void>;

// Called when module is disabled for a tenant
onDisable?: (tenantId: string) => Promise<void>;

Use Cases

• Seed default data when enabled
• Clean up resources when disabled
• Send notifications
• Initialize external services

---

Landing Page Integration

Modules can contribute content to project public landing pages.

Landing Section

interface ModuleLandingSection {
  title: string;       // Section title
  description: string; // Section description
  features: string[];  // Feature bullet points
  icon?: string;       // SVG icon name
  order?: number;      // Display order (lower = first)
}

Example

landingSection: {
  title: 'Team Collaboration',
  description: 'Work together with your team in real-time.',
  features: [
    'Invite unlimited team members',
    'Role-based access control',
    'Real-time collaboration',
  ],
  icon: 'users',
  order: 10,
}

Site Pages

Modules can indicate they provide public site pages:

providesSitePages: true

This is used by modules like end-user-auth that provide login/signup pages.

Landing + Core Module Behavior

• The landing page is rendered by the platform and may choose a core-module template (based on coreModuleId) for the hero and primary CTA.
• Modules should still provide landingSection for secondary sections, but must not assume it controls the full landing layout.

---

Project Site Context Resolution

When building pages for project subdomains (e.g., myproject.credsnet.com), you must handle the case where the project context is not available from middleware headers (cache miss scenario).

The Problem

The middleware uses Vercel KV to cache project data for fast edge resolution. When a project is first accessed or the cache expires, the middleware sets x-project-cache-miss: true but cannot set project-specific headers like x-project-slug because the data isn't in cache.

The Solution

Use the resolveProjectContext() utility function which handles both scenarios:

// apps/web/src/app/site/utils.ts
import { resolveProjectContext } from './utils';

export default async function MyProjectPage() {
  // This handles both cache hit and miss
  const projectContext = await resolveProjectContext();
  
  if (!projectContext) {
    notFound();
  }
  
  // Now you have: projectId, projectSlug, projectTenantId, projectName, projectStatus
  const { projectSlug, projectTenantId } = projectContext;
  
  // Fetch full project data
  const project = await getProjectBySlugGlobal(projectSlug);
  // ...
}

How It Works

1. Cache Hit: Middleware sets headers (x-project-id, x-project-slug, etc.) from KV cache
2. Cache Miss: The utility extracts the slug from the host header and queries the database
3. Auto-Cache: On cache miss, the project is automatically cached for future requests

Important: All Site Pages Must Use This Pattern

Every page under /app/site/ must use resolveProjectContext() instead of directly reading headers:

// ❌ WRONG - Will fail on cache miss
const projectSlug = headersList.get('x-project-slug');
if (!projectSlug) notFound();

// ✅ CORRECT - Handles both cache hit and miss
const projectContext = await resolveProjectContext();
if (!projectContext) notFound();

The Utility Function

// apps/web/src/app/site/utils.ts

export interface ResolvedProjectContext {
  projectId: string;
  projectSlug: string;
  projectTenantId: string;
  projectName: string;
  projectStatus: string;
}

export async function resolveProjectContext(): Promise<ResolvedProjectContext | null> {
  const headersList = await headers();
  
  // Try middleware headers first
  let projectId = headersList.get('x-project-id');
  let projectSlug = headersList.get('x-project-slug');
  // ... other headers
  
  // If we have all data, return it
  if (projectId && projectSlug && projectTenantId && projectName) {
    return { projectId, projectSlug, projectTenantId, projectName, projectStatus };
  }
  
  // Handle cache miss - extract from host header
  const host = headersList.get('host') || '';
  const extractedSlug = extractSlugFromHost(host);
  
  if (extractedSlug) {
    const dbProject = await getProjectBySlugGlobal(extractedSlug);
    if (dbProject) {
      // Cache for future requests
      cacheProject(dbProject).catch(() => {});
      return {
        projectId: dbProject.id,
        projectSlug: dbProject.slug,
        // ...
      };
    }
  }
  
  return null;
}

---

Module Registration

Every module must register itself at the end of its index.ts:

import { registerModule, type ModuleDefinition } from '@v2/modules';

export const myModule: ModuleDefinition = {
  metadata: { /* ... */ },
  // ... other properties
};

// Auto-register module
registerModule(myModule);

// Export for direct imports
export default myModule;

---

Security Requirements

Mandatory Requirements

1. RLS on all tables: Every table must have Row-Level Security enabled
2. Tenant isolation: All queries must be scoped to the current tenant
3. Route RBAC: API routes must explicitly declare minimumRole
4. Input validation: All user input must be validated
5. SQL injection prevention: Use parameterized/tagged queries only
6. Migration linting: Module migrations must pass pnpm lint:module-migrations
7. Raw query guard: Do not import query from @v2/database in app/module code (guarded by pnpm lint:no-raw-query)

Prohibited Practices

• Direct SQL string concatenation
• Importing raw query into module feature code
• Accessing other modules' tables directly
• Bypassing RLS without explicit admin context
• Omitting minimumRole on module admin API routes
• Storing sensitive data unencrypted
• Exposing internal IDs in URLs

Database Access

Always use the provided database utilities:

import { withTenantProjectQuery, withTenantQuery, getPrivilegedRuntimeDb } from '@v2/database';

// Preferred for project-scoped runtime queries
const results = await withTenantProjectQuery(tenantId, projectId, (sql) => sql`
  SELECT * FROM my_table
  WHERE project_id = ${projectId}
`);

// Tenant-only runtime queries (no project context)
const tenantRows = await withTenantQuery(tenantId, (sql) => sql`
  SELECT * FROM tenant_settings
`);

// Privileged runtime operations (control plane only; avoid in feature handlers)
const privileged = getPrivilegedRuntimeDb();

---

Best Practices

Naming Conventions

Code Organization

src/
├── index.ts           # Module definition only
├── api/
│   ├── contacts.ts    # Contact-related handlers
│   └── deals.ts       # Deal-related handlers
├── pages/
│   ├── contacts-page.tsx
│   └── deals-page.tsx
├── components/
│   ├── contact-form.tsx
│   └── deal-card.tsx
└── lib/
    ├── queries.ts     # Database queries
    └── utils.ts       # Utility functions

Event Naming

Events should be namespaced and descriptive:

eventsEmitted: [
  'crm.contact.created',
  'crm.contact.updated',
  'crm.contact.deleted',
  'crm.deal.won',
  'crm.deal.lost',
]

---

Example Module

Here's a complete example of a minimal module:

// modules/notes/src/index.ts

import { registerModule, type ModuleDefinition } from '@v2/modules';
import { NotesPage } from './pages/notes-page';
import { handleGetNotes, handleCreateNote, handleDeleteNote } from './api/notes';

export const notesModule: ModuleDefinition = {
  metadata: {
    id: 'notes',
    name: 'Notes',
    description: 'Simple note-taking for your workspace',
    version: '1.0.0',
    icon: 'note',
    category: 'operations',
    defaultEnabled: false,
    
    features: [
      'Create and organize notes',
      'Rich text formatting',
      'Search across all notes',
    ],
    
    tags: ['notes', 'productivity', 'documentation'],
    
    eventsEmitted: [
      'notes.note.created',
      'notes.note.updated',
      'notes.note.deleted',
    ],
    
    landingSection: {
      title: 'Notes & Documentation',
      description: 'Keep all your important information in one place.',
      features: [
        'Unlimited notes',
        'Rich text editor',
        'Full-text search',
      ],
      icon: 'note',
      order: 20,
    },

    requiredSiteCapabilities: [
      'layout.publicHeader',
      'layout.workspaceContent',
      'ui.navigation.moduleLinks',
      'ui.surface.card',
      'ui.form.controls',
      'ui.feedback.error',
      'ui.data.list',
      'ui.data.keyValue',
    ],
  },

  // Backoffice (project-owner) layer
  projectAdminNavigation: [
    {
      label: 'Notes',
      href: '/',
      icon: 'note',
    },
  ],

  projectAdminPages: {
    '/': NotesPage,
  },

  projectAdminApiRoutes: [
    { method: 'GET', path: '/notes', handler: handleGetNotes, minimumRole: 'member' },
    { method: 'POST', path: '/notes', handler: handleCreateNote, minimumRole: 'admin' },
    { method: 'DELETE', path: '/notes/:id', handler: handleDeleteNote, minimumRole: 'admin' },
  ],

  permissions: [
    {
      id: 'notes:notes:read',
      name: 'View Notes',
      description: 'Can view notes',
    },
    {
      id: 'notes:notes:write',
      name: 'Manage Notes',
      description: 'Can create, edit, and delete notes',
    },
  ],

  migrations: [
    {
      name: '0001_create_notes_table',
      up: `
        CREATE TABLE IF NOT EXISTS notes_notes (
          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
          tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
          title VARCHAR(255) NOT NULL,
          content TEXT,
          created_by UUID REFERENCES users(id),
          created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
          updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
        );
        
        CREATE INDEX IF NOT EXISTS idx_notes_notes_tenant 
          ON notes_notes(tenant_id);
        
        ALTER TABLE notes_notes ENABLE ROW LEVEL SECURITY;
        ALTER TABLE notes_notes FORCE ROW LEVEL SECURITY;
        
        CREATE POLICY notes_notes_select ON notes_notes
          FOR SELECT USING (tenant_id = current_tenant_id());
        CREATE POLICY notes_notes_insert ON notes_notes
          FOR INSERT WITH CHECK (tenant_id = current_tenant_id());
        CREATE POLICY notes_notes_update ON notes_notes
          FOR UPDATE USING (tenant_id = current_tenant_id());
        CREATE POLICY notes_notes_delete ON notes_notes
          FOR DELETE USING (tenant_id = current_tenant_id());
        
        GRANT SELECT, INSERT, UPDATE, DELETE ON notes_notes TO app_user;
      `,
      down: `DROP TABLE IF EXISTS notes_notes;`,
    },
  ],

  // Public (end-user) layer (optional)
  sitePages: {
    '/notes': NotesPublicPage,
  },

  siteNavigation: [{ label: 'Notes', href: '/notes', icon: 'note' }],

  onEnable: async (tenantId: string) => {
    console.log(`[Notes Module] Enabled for tenant ${tenantId}`);
  },

  onDisable: async (tenantId: string) => {
    console.log(`[Notes Module] Disabled for tenant ${tenantId}`);
  },
};

// Auto-register module
registerModule(notesModule);

export default notesModule;

---

Version History

---

Questions?

For questions about module development, refer to:

• Internal documentation at /docs
• Module examples in /modules
• Type definitions in @v2/modules