Module Development — Getting Started

git clone https://github.com/septemcore/platform-kernel.git
cd platform-kernel/.dev/kernel

# Start the full stack: PostgreSQL, ClickHouse, Kafka, RabbitMQ,
# Valkey, Vault, and all 12 Go services
docker compose -f docker/docker-compose.yml up -d

# Check readiness
docker compose -f docker/docker-compose.yml ps

npx @platform/create-module@latest my-crm --description "A simple CRM module"
cd my-crm
pnpm install

my-crm/
├── module.manifest.json   ← Module contract (read by the Registry)
├── federation.config.js   ← Module Federation 2.0 remote config
├── package.json
├── tsconfig.json
├── src/
│   └── pages/
│       └── index.tsx      ← Main React 19 entry component
└── migrations/            ← SQL migrations (pressly/goose format)

{
  "name": "@demo/my-crm",
  "version": "1.0.0",
  "description": "A simple CRM module",
  "kernelSdkVersion": "^1.0.0",
  "entry": "",
  "exposedComponent": "MyCrmModule",
  "route": "/crm",
  "icon": "Users",
  "category": "crm",
  "permissions": ["crm.contacts.read", "crm.contacts.write"],
  "events": {
    "publishes": ["crm.contact.created"],
    "subscribes": ["auth.user.created"]
  },
  "dataApi": {
    "models": ["contacts", "deals"]
  },
  "healthCheck": "/health",
  "dependencies": {
    "@platform/sdk-auth": "^1.0.0",
    "@platform/sdk-data": "^1.0.0"
  }
}

# Core package (always required)
pnpm add @platform/sdk-core

# Add primitives as needed
pnpm add @platform/sdk-auth    # Auth, RBAC, session management
pnpm add @platform/sdk-data    # CRUD, realtime, analytics queries
pnpm add @platform/sdk-events  # Kafka / browser event publish & subscribe
pnpm add @platform/sdk-notify  # Notifications (WebSocket, email, SMS)
pnpm add @platform/sdk-files   # File upload, image processing, thumbnails
pnpm add @platform/sdk-money   # Wallets, credit/debit, holds, transfers
pnpm add @platform/sdk-audit   # Audit trail recording

# UI Design System (optional)
pnpm add @platform/sdk-ui

# Development tools
pnpm add -D @platform/sdk-testing   # Vitest mocks and fixtures

import { useAuth } from "@platform/sdk-auth";
import { useQuery } from "@platform/sdk-data";

interface Contact {
  id: string;
  name: string;
  email: string;
  created_at: string;
}

export default function MyCrmModule() {
  const { user, tenant } = useAuth();

  // Resolves to: GET /api/v1/data/my-crm/contacts?page_size=20
  // RLS ensures only current tenant's rows are returned.
  const { data: contacts, isLoading } = useQuery<Contact>(
    "my-crm",
    "contacts",
    { page_size: 20, order: "created_at.desc" }
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>{tenant.name} — CRM</h1>
      <p>Signed in as {user.email}</p>
      <ul>
        {contacts?.data.map((c) => (
          <li key={c.id}>{c.name} — {c.email}</li>
        ))}
      </ul>
    </div>
  );
}

import { publish } from "@platform/sdk-events";

await publish({
  topic: "platform.module.events",
  type: "crm.contact.created",
  entityId: contact.id,
  tenantId,
  payload: { contactId: contact.id, name: contact.name },
  idempotencyKey: crypto.randomUUID(),
});

import { defineConfig } from "@module-federation/vite";

export default defineConfig({
  name: "crm",
  exposes: {
    "./App": "./src/App",
  },
  shared: {
    react:         { singleton: true, requiredVersion: "^19.0.0" },
    "react-dom":   { singleton: true, requiredVersion: "^19.0.0" },
    "react-router-dom": { singleton: true, requiredVersion: "^7.0.0" },
    zustand:       { singleton: true, requiredVersion: "^5.0.0" },
    "@platform/sdk-core": { singleton: true },
    "@platform/sdk-auth": { singleton: true },
  },
});

# Start the dev server (hot-reload, proxied to sandbox API)
pnpm dev
# → Remote available at http://localhost:5173/remoteEntry.js

# Register the module (reads module.manifest.json automatically)
npx @platform/create-module register \
  --gateway http://localhost:8080 \
  --token <admin_jwt_from_sandbox> \
  --entry http://localhost:5173/remoteEntry.js

# Activate for the demo tenant
npx @platform/create-module activate \
  --gateway http://localhost:8080 \
  --token <admin_jwt_from_sandbox>

POST /api/v1/modules/install
  → pending → installing → active / failed

pnpm build
# Generates: dist/remoteEntry.js, dist/assets/, dist/module.manifest.json

npx @platform/create-module publish \
  --gateway https://api.septemcore.com \
  --token <platform_owner_jwt>

https://cdn.platform.io/modules/{tenantId}/{moduleId}/{version}/remoteEntry.js

migrations/
├── 001_create_contacts.sql
└── 002_add_contact_tags.sql

npx @platform/cli module migration force-version \
  --module my-crm --version 1

"permissions": [
  "crm.contacts.read",
  "crm.contacts.write",
  "crm.deals.read",
  "crm.deals.write"
]

import { useRBAC } from "@platform/sdk-auth";

const { can } = useRBAC();
if (can("crm.contacts.write")) {
  // Show edit button
}