DEVELOPER SDK & EXTENSION GUIDES

Developer Documentation

Learn how to build, extend, and deploy Modulogium. Access the type-safe TypeScript SDK (@modulogium/core), terminal CLI, and community module authoring APIs.

modulogium-cli — zsh

$npx modulogium init my-company --recipe=b2b-saas

📦 Fetching canonical Modulogium v0.8.4 primitives...

✓ Scaffolding 10 universal entity tables (PostgreSQL/SQLite)

✓ Installing 6 recipe modules (@modulogium/mod-crm, mod-billing, mod-analytics, ...)

✓ Generating TypeScript types into ./src/schema.d.ts

🚀 Modulogium workspace initialized in ./my-company

Next steps:

cd my-company

npx modulogium studio # Opens visual composer at http://localhost:3000

Getting Started

Quickstart & Installation

Spin up a local Modulogium instance in under 60 seconds with your chosen recipe.

The Modulogium CLI initializes a standalone TypeScript project configured with the 10 universal primitives and your selected modules.

By default, development runs on an embedded SQLite database or connects directly to your local PostgreSQL instance.

The local runtime includes the web dashboard, GraphQL/REST API endpoints, and real-time reactive event bus.

# Initialize a new Modulogium workspace with the B2B SaaS recipe
npx modulogium init my-org --recipe=b2b-saas --database=postgres

# Navigate into project and start local dev runtime
cd my-org
npm run dev

# Open the Foundry Composer at http://localhost:3000

Core SDK

Core SDK (@modulogium/core)

Type-safe programmatic interface for querying, mutating, and extending organizational primitives.

@modulogium/core provides an ergonomic, fully type-safe ORM and reactive query builder.

All extensions declared by installed modules are automatically merged into TypeScript generics for end-to-end auto-completion.

Transactions are atomic across all primitive boundaries with automatic audit log tracking.

import { createClient } from "@modulogium/core";
import { crmExtension } from "@modulogium/mod-crm";

const client = createClient({
  databaseUrl: process.env.DATABASE_URL!,
  modules: [crmExtension],
});

// Query a Person primitive with attached CRM and HR extensions
const person = await client.person.findById("019183ab-45cd-7e89-b012-3456789abcde", {
  include: ["relationships", "interactions", "tasks"],
});

console.log(person.displayName);          // Universal Primitive field
console.log(person.extensions.crm.leadScore); // Injected by CRM module

Module Development

Building Custom Modules

Step-by-step guide to authoring, publishing, and registering community modules.

Any contributor can author a module using the `defineModule` DSL.

Modules can inject custom properties into primitives, declare new polymorphic views, and subscribe to life-cycle events.

Publish your module to npm and submit a pull request to the Modulogium Registry to make it discoverable in the Foundry.

import { defineModule } from "@modulogium/core/builder";

export default defineModule({
  id: "warranty-tracker",
  name: "Warranty & RMA Tracker",
  version: "1.0.0",
  // 1. Extend universal primitives
  extends: {
    Asset: {
      warrantyExpiresAt: { type: "timestamp", required: false },
      rmaCount: { type: "integer", default: 0 },
    },
  },
  // 2. Declare reactive event triggers
  on: {
    "Asset.quantity_updated": async ({ event, client }) => {
      // Custom business logic
    },
  },
});

CLI Reference

CLI Command Reference

Complete syntax for the `modulogium` terminal toolchain.

The CLI manages database schema migrations, module installations, code generation, and developer studio environments.

Works in CI/CD pipelines for automated schema validation and regression testing.

# Scaffold new workspace
modulogium init [name] [--recipe=<recipe>] [--database=<engine>]

# Add or remove modules
modulogium module add <package-name>
modulogium module remove <package-name>
modulogium module list

# Schema migrations & code generation
modulogium schema generate
modulogium schema migrate
modulogium schema export --format=typescript|prisma|sql

# Start development studio
modulogium studio --port=3000