Documentation

Build on a deterministic infrastructure runtime.

Architecture references, API contracts, and module development guides for teams building high-trust products on top of Altason.

Documents

Sections

Primary Audience

Systems builders

Developers

Module developer guide

How to build submit-ready modules for the marketplace.

Reference

Goal

This guide defines what an external developer must build to submit a module to the BusinessOS marketplace.

The submission system will be built later. These rules are enforced now to keep the platform consistent and secure.

Required: Two-layer module architecture

Every module must support two operational layers:

Project-owner backoffice layer

projectAdminNavigation: injects links under Project Modules in the project sidebar
projectAdminPages: pages mounted under /p/:slug/modules/:moduleId/...
projectAdminApiRoutes: APIs mounted under /api/projects/:projectId/modules/:moduleId/...

Backoffice pages must:

require builder auth (platform handles)
be project-scoped (use context.projectId and context.projectSlug)
never assume a single-project tenant

End-user/public layer (optional)

sitePages: pages mounted under the project host (internally rewritten to /site/...)
siteApiRoutes: authenticated end-user APIs mounted under /api/site/modules/:moduleId/...
siteNavigation: end-user header navigation links (the platform header renders them)

End-user pages must:

resolve project context via platform context (SiteModulePageProps.context)
never render admin components
never create their own global headers (platform header is shared)

Required: Multi-tenancy + RLS

All module data must be tenant-scoped:

Every table must include tenant_id UUID NOT NULL
Project-facing tables should also include project_id UUID NOT NULL REFERENCES projects(id)
Enable RLS + FORCE RLS
Add policies using tenant_id = current_tenant_id()
Grant privileges to app_user

Required: Database access contract

Runtime module queries must use withTenantProjectQuery(...) where project context exists
Tenant-level module queries may use withTenantQuery(...)
Do not use getAdminDb() in module runtime code
Do not run DDL from module request handlers
Keep query predicates explicitly filtered by project_id for project-facing data

Required: API RBAC contract

All module admin APIs must declare explicit access levels.

Every entry in projectAdminApiRoutes must set minimumRole
If a module still uses legacy apiRoutes, each of those route entries must also set minimumRole
Use:
- minimumRole: 'member' for read/list/view endpoints
- minimumRole: 'admin' for create/update/delete/publish/configure endpoints
- minimumRole: 'owner' only for tenant-critical operations
Do not rely on router fallback role inference for new code
Keep permissions aligned with route intent, but treat minimumRole as the enforcement source
If permissions are used without minimumRole (legacy only), permission suffixes must be one of: read|list|view|write|create|update|delete|publish|manage|admin|configure Unknown suffixes fail closed with ROUTE_PERMISSION_CONFIG_ERROR
Avoid ad-hoc membership role checks inside route handlers unless you are enforcing stricter business rules than route-level RBAC

Required: Payments Core rule

If the module is monetized:

it must depend on payments-core
it must use entitlements for access decisions
it must not integrate Stripe directly

Required: UI/Design rules

Use the platform tonal surface system (bg-surface*, border-border, text-content*)
Use border-based structure, not heavy shadows
Icons must be SVG icon names (no emojis)
Public pages must use text-site-* and bg-site-* tokens

Optional: Legacy dashboard contract (deprecated)

Do not build new modules around /dashboard.

If you must support legacy projects:

declare metadata.siteDashboardSections
expose section data via siteApiRoutes
return small, cache-friendly JSON (no large lists)

Submission checklist (what we review)

Architecture

Uses project-owner and public layers correctly
No cross-module direct DB access
Runtime queries use withTenantProjectQuery/withTenantQuery (no raw privileged client)
Every projectAdminApiRoutes entry sets explicit minimumRole
Legacy apiRoutes entries (if present) set explicit minimumRole
No new code relies on method-based RBAC fallback
RLS policies present + correct
No direct payment provider usage outside Payments Core
Handles missing sessions cleanly (401/403) for site APIs

UI / Design

Icons are SVG icon names only
Uses siteNavigation correctly
Public pages use site-section, site-container, and --site-* tokens

Migrations

Provides migrations with clear names and safe down scripts
Passes pnpm lint:module-migrations (no missing RLS, no unscoped tables)

Template compatibility

metadata.requiredSiteCapabilities declares every site theme capability the module needs (typed as ModuleSiteThemeCapability[], sourced from the MODULE_SITE_THEME_CAPABILITIES constant exported by @v2/modules)
Unknown capability IDs are rejected at module registration (enforced by registerModule())
Module install is blocked by the platform when the current project template lacks required capabilities
TypeScript compiles cleanly: pnpm --filter @v2/modules exec tsc --noEmit