Adapstory Developer Docs

Adapstory's core is six bounded contexts. Each runs as its own service with its own PostgreSQL database. Cross-BC communication is REST or Kafka — never shared tables.

BC-01 — Plugin Gateway

Owns: MCP tool registry, LLM routing, guardrail enforcement, token budgeting.

You care about: every plugin's MCP tools register here. When an LLM in the platform invokes a tool, this BC routes the call, checks the tenant's budget, applies guardrails, and returns the response.

Contract:

Registration: POST /bc-01/mcp/tools (from Plugin Lifecycle at install-time)
Invocation: POST /bc-01/mcp/invoke (from LLMs via Gateway)
Budget check: fail-closed if tenant is over limit

BC-02 — Plugin Lifecycle

Owns: plugin manifests, install/update/rollback state machines, image signature verification.

You care about: this is the BC you talk to when shipping a new version. It verifies Cosign signatures, applies Kyverno policies, and calls BC-19 to schedule the workload.

State machine:

DRAFT → SIGNED → VERIFIED → INSTALLING → ACTIVE
                                    ↘ FAILED → ROLLED_BACK

BC-10 — Identity

Owns: users, tenants, roles, SSO configuration. Keycloak sits underneath.

You care about: when your plugin needs to know who is calling, read the JWT claims — don't query BC-10 directly except to resolve role memberships you don't already have.

BC-15 — Data Model Engine

Owns: the dynamic schema. Tenants can extend the model (add entities, add attributes) at runtime. BC-15 keeps the schema, the data, and the event projections consistent.

Plugins that extend core entities (e.g., adding an attribute to course) register their extensions here. The Data Model Engine enforces compatibility and versions schema migrations like code.

Primary API:

POST /bc-15/entities/{type} — create
PATCH /bc-15/entities/{type}/{id} — partial update (CloudEvents under the hood)
POST /bc-15/schemas/{type}/migrations — ship a schema change

BC-16 — Identity Runtime

Owns: short-lived JWTs, token introspection, per-tenant signing keys.

You care about: validate incoming JWTs with this BC (or use the shared libs that wrap it). Don't store tokens. Rotate keys aggressively.

BC-19 — Multi-Tenant Runtime

Owns: scheduling, isolation, secrets injection, resource limits.

You care about: this is what runs your plugin. It decides which node, which namespace, which secrets get mounted. You declare limits in plugin.yaml; it enforces them.

Guarantees:

Tenant namespaces have pod-security.kubernetes.io/enforce: restricted
Secrets flow Vault → ESO → Kubernetes Secret. Never baked into images.
Network policies deny cross-tenant traffic by default.

Plugin's place

Plugins live outside core. They integrate by:

Calling core APIs over HTTP (with a service-account JWT from BC-16).
Producing or consuming Kafka events in CloudEvents format.
Registering MCP tools with BC-01 for LLM-driven invocation.

They do not:

Open direct database connections to core BCs.
Share in-memory state with other plugins.
Bypass the LLM Gateway for model calls.

Next: Plugin quickstart.

Bounded contexts