Backend Packages

This section documents the future Prox OS backend package system. It is a documentation-only map for now: do not create these packages until the relevant contract, testing harness, fixtures, permission model, and acceptance checklist exist.

Long-term direction:

Cloudflare-first, Hono-powered, OpenAPI-readable, PostgreSQL-centered,
permission-aware, AI-agent-ready backend package system.

Current Reality

• apps/api-worker is the Cloudflare Worker / Hono runtime container.
• packages/data/db and packages/backend/storage already exist as early package placeholders or foundations, but this document does not expand them into production backend services.
• Backend capabilities should live in packages/*, not directly inside the API runtime container.
• API work should be contract-first, test-first, permission-aware, observable, and auditable before real business data enters the system.

Backend Package Set

Documentation Map

• Package Graph: layers, dependency graph, event flow, and Cloudflare-first runtime direction.
• Package Radar: status, priority, triggers, package records, risks, and implementation readiness.
• Package Boundaries: allowed dependency direction, non-goals, frontend bridges, and real app scenarios.
• AI-generated Backend: why backend generation needs gates, required artifacts, and future AI worker roles.
• Testing Strategy: unit, contract, integration, migration, permission, webhook, job, billing, audit, and agent tests.

Roadmap Stages

Stage 0: Documentation-only backend map

Current stage. The package graph, radar, boundaries, AI generation gates, and testing strategy are documented. Real backend package creation is intentionally out of scope.

Stage 1: API Worker skeleton hardening

Start with @prox-os/api-contract, @prox-os/api-kit, and @prox-os/observability. Harden health routes, OpenAPI docs, request IDs, standard errors, and a local test runtime.

Stage 2: Database foundation

Start @prox-os/db with migration convention, local/test/prod separation, seeds, fixtures, and the first minimal schema. Do not create broad product schemas without tests and rollback plans.

Stage 3: Identity and permission foundation

Introduce @prox-os/auth, @prox-os/permissions, and @prox-os/audit together so protected routes, session context, app permissions, and audit trails appear before sensitive features.

Stage 4: First real app backend

Pick one pilot app, such as Moments, Media, Dreams, or Tips. Do not activate all backend packages at once.

Stage 5: Automation, webhooks, search

Bring in @prox-os/jobs, @prox-os/webhooks, @prox-os/search-service, and @prox-os/notifications-service after the data and permission model is testable.

Stage 6: Agents runtime and commercial layer

Add @prox-os/agents-runtime and @prox-os/billing only after permissions, audit, jobs, and webhook replay are stable enough to govern tool calls and payment events.

Frontend Package Bridges

App Scenarios

Moments App

Moments would use storage for photo uploads, media-service for thumbnails and EXIF cleanup, db for moment records, permissions for visibility, search-service for photo/place/text search, future map services for EXIF location, audit for access and edits, and agents-runtime for AI captions or AI albums.

Dreams App

Dreams would use db for private dream records, search-service for symbols, agents-runtime for reflective AI interpretation, permissions for private by default access, audit for sensitive access, and notifications-service for journaling reminders.

Tips / Billing App

Tips would use billing for tips and subscriptions, webhooks for payment events, jobs for post-payment processing, notifications-service for thank-you notifications, audit for payment state transitions, and permissions for entitlements.

Badges App

Badges would use webhooks for GitHub star or PR events, jobs for badge awarding, db for badge state, notifications-service for unlocked badges, and audit for award records.

App Store / External Apps

The App Store would use permissions for app install scopes, api-contract for public app APIs, agents-runtime for app tools, audit for external app actions, and billing for paid apps or revenue sharing.

Non-Goals

• Do not create the 15 packages now.
• Do not write real backend business code now.
• Do not create production DB schema or migrations now.
• Do not connect Stripe, OAuth, R2, real search, real agents, or real billing until the package gates are met.
• Do not let AI generate untestable backend complexity.