# Docs: Extension Model

Extensions are bounded capability slices on the shared base. The detailed reference below covers runtime shape, routing, events, storage, and review boundaries.

## Summary

- Bounded by core: Extensions rely on the shared system model rather than creating a separate one.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
- Definition: docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md) — Defines when work belongs in the instance repo versus a separate extension repo.
- Contract: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
- Implementation: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Shows the canonical public scaffold for bounded custom extension authoring.

- Runtime classes are explicit: Bundle and service-backed runtimes carry different storage, routing, and lifecycle implications.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Owned schema is available when needed: Service-backed extensions can own an `ext_*` PostgreSQL schema and migration history without leaking into core tables.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Pairs with security: Extension evaluation belongs beside the trust and deployment model.
  Proof:
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Requires extensions to use the same outbox and event-bus pattern as core whenever they publish or consume events.
- Implementation: internal/infrastructure/stores/shared/interfaces.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/shared/interfaces.go) — Defines the shared outbox and idempotency interfaces used for reliable event publishing and handling.
- Implementation: internal/infrastructure/stores/sql/analytics_db.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/analytics_db.go) — Shows the analytics extension using its own `ext_demandops_web_analytics` schema.
- Implementation: internal/infrastructure/stores/sql/error_monitoring_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/error_monitoring_store.go) — Shows the error-tracking extension using its own `ext_demandops_error_tracking` schema.


## The extension model exists so domain depth can grow on top of a strong shared base.

The key value is not merely that extensions are possible. The key value is that extensions inherit shared identity, routing, queues, cases, knowledge, audit, CLI access, and GraphQL access. That makes extension code smaller and makes evaluation easier for agents.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
- Definition: docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md) — Defines when work belongs in the instance repo versus a separate extension repo.
- Contract: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
- Implementation: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Shows the canonical public scaffold for bounded custom extension authoring.

- Why not separate apps: Separate apps rebuild auth, routing, and work records over and over again. Bounded extensions reuse those layers instead.
- Why agents care: Agents can inspect the same primitives, CLI verbs, and lifecycle states across core and extensions instead of learning a fresh control plane for each capability slice.

## Bundle and service-backed runtimes have different responsibilities.

A bundle extension stays mostly declarative. A service-backed extension adds handlers, jobs, consumers, and extension-owned state while still living behind core-owned routing and lifecycle controls.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Bundle runtime: Best for workflow extensions, admin pages, public pages, bundled skills, seeded knowledge, and declarative product slices that do not need their own backend process.
- Service-backed runtime: Best when the extension truly needs custom handlers, event consumers, scheduled jobs, health checks, or its own bounded runtime process.
- Owned `ext_*` schema: A service-backed `owned_schema` extension can register an extension-owned PostgreSQL schema and advance its migrations independently from core.
- Shared runtime registry: Install state, schema version, and migration status remain visible in the shared runtime store rather than hiding in ad hoc deployment scripts.

## Core owns external routing. Extensions declare endpoint classes.

The extension endpoint model is deliberate. Extensions do not open arbitrary internet-facing ports on their own. They declare endpoint classes and core mounts them into approved path families with core-owned auth, rate limits, tracing, and audit boundaries.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Public and admin pages: Asset-backed public pages and admin pages mount through core under explicit path families.
- Public ingest and webhooks: Service-backed analytics or compatibility-sensitive extensions can register public ingest or webhook endpoints through the same reviewed endpoint catalog.
- Extension APIs and health: Service-backed extensions can expose extension APIs and internal health endpoints without becoming a separate router or trust domain.

## Extensions should use the same typed-event and outbox pattern as core.

When an extension publishes or consumes domain events, it should use the same outbox and event-bus model as core. That keeps retries, idempotency, auditability, and operational visibility consistent across first-party and self-built extensions.

Proof:
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Requires extensions to use the same outbox and event-bus pattern as core whenever they publish or consume events.
- Implementation: internal/infrastructure/stores/shared/interfaces.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/shared/interfaces.go) — Defines the shared outbox and idempotency interfaces used for reliable event publishing and handling.
- Implementation: internal/infrastructure/stores/sql/analytics_db.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/analytics_db.go) — Shows the analytics extension using its own `ext_demandops_web_analytics` schema.
- Implementation: internal/infrastructure/stores/sql/error_monitoring_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/error_monitoring_store.go) — Shows the error-tracking extension using its own `ext_demandops_error_tracking` schema.

- Typed event flows: Event publishers and consumers should be explicit and inspectable rather than hidden in private scripts or side channels.
- Reliable delivery model: The shared outbox and idempotency interfaces provide the same reliability pattern core uses for durable follow-through.
- Extension-owned data stays bounded: Analytics and error-tracking demonstrate that richer product slices can keep their own bounded data model without bypassing the shared base.

## Public first-party extensions already show how different extension classes fit the model.

The site should not ask agents to imagine what an extension looks like. Use the public first-party extensions and the platform docs as concrete evidence for the model.

Proof:
- Definition: README.md (https://github.com/MoveBigRocks/extensions/blob/main/README.md) — Documents the first-party extensions repo, install refs, and release tag model.
- Catalog: catalog/public-bundles.json (https://github.com/MoveBigRocks/extensions/blob/main/catalog/public-bundles.json) — Machine-readable catalog for the free public first-party bundle set.
- Release: .github/workflows/public-bundles.yml (https://github.com/MoveBigRocks/extensions/blob/main/.github/workflows/public-bundles.yml) — Publishes the free public first-party bundle set to GHCR from the first-party extensions repo.
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Explains the bundle-first default and when to move into service-backed endpoints, jobs, consumers, and owned-schema migrations.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Gives the local lint, verify, and sandbox lifecycle for a custom extension.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Uses ATS, community feature requests, sales pipeline, web analytics, and error tracking as concrete endpoint and runtime examples.

- ATS: ATS is a bundle-first, workspace-scoped product extension with careers assets, workflow seeds, and bundled agent skills.
- Web analytics: Web analytics is the canonical example of a service-backed product extension with public ingest routes, admin pages, and an extension-owned analytics schema.
- Error tracking: Error tracking is the canonical example of a service-backed extension with compatibility-sensitive ingest aliases, issue processing, and extension-owned bounded state.
- Private workflow extensions: Customer-built private extensions can still stay on the same base when they follow the same runtime, review, and routing rules.