Backend Package Boundaries

Backend package boundaries exist to keep the API Worker small, make AI-generated

Backend package boundaries exist to keep the API Worker small, make AI-generated backend code reviewable, and prevent auth, permissions, billing, audit, jobs, and agent tooling from collapsing into one unsafe runtime.

Core Rules

Packages must not form circular dependencies.
apps/api-worker is a runtime container. It should compose routes and middleware, not own deep business logic.
@prox-os/api-contract must not depend on runtime packages.
@prox-os/api-kit must not own domain routes.
@prox-os/db must not depend on @prox-os/api-kit.
@prox-os/auth is not @prox-os/permissions.
@prox-os/audit is not @prox-os/observability.
@prox-os/storage is not @prox-os/media-service.
@prox-os/webhooks must not directly perform business side effects; it normalizes and verifies events, then sends work to jobs.
@prox-os/jobs executes async work but does not own domain policy.
@prox-os/billing must not bypass permissions or audit.
@prox-os/agents-runtime tool calls must pass permissions and emit audit events.

Package Boundary Matrix

Package	Must not depend on	Calls or references
`api-contract`	runtime middleware, DB, provider SDKs	schema tooling only
`api-kit`	app-specific business routes	`api-contract`, auth, permissions, observability
`db`	API runtime, auth sessions, app UI	database driver and migration tooling
`auth`	permission policy, billing plans	DB, observability, API middleware
`permissions`	auth provider internals, billing plans	DB, audit
`storage`	media transforms, app UI	permissions, audit, observability
`media-service`	generic object storage ownership	storage, jobs, audit
`search-service`	frontend search UI	DB, permissions, jobs
`notifications-service`	billing core, auth core	jobs, audit, permissions
`jobs`	domain policy, direct user UI	observability, audit, package payload schemas
`webhooks`	direct business side effects	api-contract, jobs, audit
`agents-runtime`	direct unaudited DB writes	permissions, jobs, audit, observability
`audit`	user notification delivery, metrics dashboards	DB, observability correlation
`billing`	permission core, notification delivery	webhooks, audit, notifications, permissions
`observability`	audit event truth, app business logic	provider adapters

Frontend Package Bridges

Existing frontend packages should stay reusable and consume backend capability through contracts and APIs:

@prox-os/data-contract can align with @prox-os/api-contract, @prox-os/db, and @prox-os/search-service.
@prox-os/data-table should use list/search/query APIs, not import DB code.
@prox-os/data-viz should use analytics/query APIs or aggregate datasets.
@prox-os/media should align with @prox-os/storage and @prox-os/media-service.
@prox-os/maps should align with future places, geocoding, routing, and tracks services.

Planned frontend areas should also stay contract-based:

Actions packages should call permissioned action APIs and audit events.
Command packages should consume search, actions, and agent APIs.
Forms packages should consume validation schemas from api-contract.
Notification UI packages should consume notifications-service APIs.
AI UI packages should consume agents-runtime run and tool-call APIs.

Real App Linkage

Moments

Moments touches storage, media-service, DB, permissions, search, map services, audit, and agents. It is a strong pilot only after storage, permissions, audit, and media fixtures exist.

Dreams

Dreams touches DB, search-service, agents-runtime, permissions, audit, and notifications. It should remain private by default and is a sensitive-data test case for permission and audit design.

Tips / Billing

Tips touches billing, webhooks, jobs, notifications, audit, and permissions. It must not start real payments until replay tests, entitlement tests, and payment readiness docs exist.

Badges

Badges touches webhooks, jobs, DB, notifications, and audit. GitHub star/PR events are useful webhook fixtures because they are low-risk compared with payments.

App Store / External Apps

External apps touch permissions, api-contract, agents-runtime, audit, billing, and webhooks. App installs must declare scopes before app actions can execute.

Implementation Rule

When a backend package becomes real, add:

package boundary doc update;
package package.json with lint/typecheck scripts;
contract or type entrypoint;
fixtures;
tests or a documented test harness;
architecture dependency rule if it protects a new boundary;
roadmap status update.

Backend Package Boundaries

On this page