Backend Package Radar

Status vocabulary:

idea -> documented -> contract-ready -> incubating -> used-by-api-worker -> tested -> stable

Current status is mostly documented. Do not treat any package in this radar as production-ready unless its status explicitly says so.

Radar Table

Package Records

@prox-os/api-contract

• Purpose: define HTTP API shape through OpenAPI schemas, route definitions, request/response schemas, pagination, errors, versioning, webhook events, and public/internal API split.
• Non-goals: no DB access, no business logic, no runtime middleware.
• Early stage: response envelope, error model, cursor/pagination types, first OpenAPI skeleton, API Worker doc alignment.
• Mid stage: generated API docs, typed client generation, contract tests, public/internal API split.
• Late stage: third-party app APIs, versioned public APIs, SDK generation, backward compatibility policy.
• Depends on: none at runtime; may share schema tooling.
• Used by: api-kit, frontend clients, docs, SDKs, webhook schemas.
• Testing strategy: schema validation, OpenAPI snapshot tests, generated client smoke tests.
• AI generation boundary: AI can add endpoints only when route contract, schema, examples, and error behavior are specified.
• Risks: schema drift, undocumented breaking changes, public/internal leakage.

@prox-os/api-kit

• Purpose: Hono runtime kit for app creation, middleware stack, request ID, CORS, errors, auth/permission context, validation, OpenAPI route registration, rate limit hooks, and standard responses.
• Non-goals: no business routes, no direct schema ownership, no app-specific policy.
• Early stage: request context, error handling, JSON response helpers, alignment with api-contract.
• Mid stage: auth middleware, permission middleware, observability middleware, OpenAPI route registration.
• Late stage: Cloudflare Workers, Node test runtime, local dev adapters, multi-tenant workspace context.
• Depends on: api-contract, observability, auth, permissions.
• Used by: apps/api-worker, local test runtime, future API workers.
• Testing strategy: middleware unit tests, local Hono adapter tests, error response snapshots.
• AI generation boundary: AI can add middleware only with documented order, context fields, failure cases, and test fixtures.
• Risks: middleware order bugs, hidden runtime coupling, inconsistent responses.

@prox-os/db

• Purpose: PostgreSQL-centered database package for Drizzle schema, migrations, relations, seed data, client factory, transactions, fixtures, role notes, Neon branch strategy, and local test database strategy.
• Non-goals: no HTTP, no UI, no dumping all business logic into schema files.
• Early stage: schema convention, migration strategy, local/test/prod env split, no broad business tables yet.
• Mid stage: user, workspace, app, file, audit, and notification base tables; migrations; seed data; integration tests.
• Late stage: multi-tenant isolation, data retention, read replicas or analytics split, migration safety automation.
• Depends on: none, except database driver/tooling.
• Used by: auth, permissions, audit, search, billing, app domain services.
• Testing strategy: migration tests, seed tests, transaction tests, fixture factories, local/branch database checks.
• AI generation boundary: AI cannot create durable schema without data model sketch, migration plan, fixtures, rollback path, and owner review.
• Risks: irreversible migrations, tenant leakage, accidental production data writes, overmodeled schemas.

@prox-os/auth

• Purpose: user identity, anonymous users, OAuth abstraction, session lifecycle, magic link direction, anonymous upgrade, device/session management, auth middleware integration, token/session rotation.
• Non-goals: no permission policy, no billing entitlement, no app-specific access rules.
• Early stage: auth boundary, anonymous/signed-in/workspace member distinction, session context.
• Mid stage: OAuth providers, session persistence, email magic link, auth middleware.
• Late stage: organization identity, SCIM/SAML direction, passkeys, device trust.
• Depends on: db, observability.
• Used by: api-kit, permissions, user/profile APIs.
• Testing strategy: session fixtures, OAuth callback mocks, token rotation tests, anonymous upgrade tests.
• AI generation boundary: AI can scaffold only provider-agnostic flows until security review and test provider mocks exist.
• Risks: account takeover, token leakage, session confusion, provider lock-in.

@prox-os/permissions

• Purpose: RBAC, ABAC, scopes, app permissions, resource permissions, AI agent permissions, policy evaluation helpers, and permission audit event shape.
• Non-goals: no auth identity, no billing plans, no notification delivery.
• Early stage: permission vocabulary, app permission scopes, resource check shape.
• Mid stage: workspace roles, app install permission grants, API middleware integration, permission tests.
• Late stage: user-defined policies, external app sandbox permissions, agent tool approvals, fine-grained object permissions.
• Depends on: db, audit.
• Used by: api-kit, storage, billing, agents, app installs, search filters.
• Testing strategy: policy matrix tests, deny-by-default fixtures, grant/revoke tests, resource ownership tests.
• AI generation boundary: AI cannot add new scopes without vocabulary docs, negative tests, audit event shape, and owner review.
• Risks: privilege escalation, implicit allow, stale grants, agent tool abuse.

@prox-os/storage

• Purpose: object storage abstraction for R2 and future adapters, bucket config, object key strategy, signed upload/download URLs, private access, metadata, checksum, lifecycle policy, and upload constraints.
• Non-goals: no image processing, no media UI, no permissions policy ownership.
• Early stage: storage resource contract, key naming strategy, public/private object boundary.
• Mid stage: R2 adapter, signed URLs, upload sessions, file metadata integration.
• Late stage: multi-region backup, cold storage, user-owned export, quota enforcement.
• Depends on: permissions, audit, observability.
• Used by: media-service, Moments, exports, attachments.
• Testing strategy: mock R2 adapter, signed URL tests, object key snapshots, private/public access tests.
• AI generation boundary: AI can add provider adapters only behind the storage interface and mock provider tests.
• Risks: public data leakage, broken signed URLs, quota bypass, object key collisions.

@prox-os/media-service

• Purpose: backend media service for image transforms, thumbnail generation, Cloudflare Images adapter, R2 variants, EXIF cleanup, metadata extraction, avatar/cover variants, AI media provenance, and moderation hook direction.
• Non-goals: no frontend media components, no generic storage adapter.
• Early stage: media asset model, variant naming, EXIF/privacy policy.
• Mid stage: R2 plus Cloudflare transform integration, thumbnail worker, media metadata endpoint.
• Late stage: Media Library backend, AI media provenance, deduplication, moderation/abuse pipeline.
• Depends on: storage, jobs, audit, observability.
• Used by: @prox-os/media, Moments, profiles, app covers.
• Testing strategy: fixture images, metadata extraction mocks, EXIF cleanup tests, variant naming snapshots.
• AI generation boundary: AI cannot process user media without privacy policy, fixture media, and test adapter.
• Risks: private metadata leakage, expensive transforms, unsafe uploads, moderation gaps.

@prox-os/search-service

• Purpose: full-text search, future vector search, indexing pipeline, query model, filters/facets, permission filtering, app-specific adapters, ranking notes.
• Non-goals: no frontend search UI, no permissions bypass.
• Early stage: searchable resource contract, Postgres full-text baseline, search result envelope.
• Mid stage: indexing pipeline, app search adapters, permission-aware search, Meilisearch/Typesense evaluation.
• Late stage: vector search, hybrid search, personal AI memory search, cross-app semantic search.
• Depends on: db, permissions, jobs, observability.
• Used by: command palette, data apps, Dreams symbols, Moments, App Store.
• Testing strategy: query fixtures, ranking snapshots, permission-filtered results, indexing job idempotency tests.
• AI generation boundary: AI can add indexes only with resource contract, permission filter tests, and expected result fixtures.
• Risks: leaking private results, stale indexes, ranking drift, costly queries.

@prox-os/notifications-service

• Purpose: notification events, inbox model, delivery channels, preferences, digests, templates, read/unread state, actor/resource refs.
• Non-goals: no billing itself, no auth itself.
• Early stage: notification contract, event-to-notification mapping, in-app only.
• Mid stage: email digest, web push, preferences, jobs integration.
• Late stage: cross-workspace routing, agent notifications, community notifications, anti-spam controls.
• Depends on: jobs, audit, permissions, observability.
• Used by: billing, agents, badges, reminders, app events.
• Testing strategy: template snapshots, preference matrix tests, delivery mock tests, digest fixtures.
• AI generation boundary: AI can add notification types only with template, preference, and spam boundary docs.
• Risks: spam, privacy leaks, duplicate notifications, notification fatigue.

@prox-os/jobs

• Purpose: queues, scheduled jobs, retries, dead letters, cron, agent tasks, webhook processing, payload schemas, idempotency keys, job observability.
• Non-goals: no business domain ownership, no bypassing audit or observability.
• Early stage: job contract, idempotency policy, Cloudflare Queues/Cron Triggers/Workflows direction.
• Mid stage: queue adapter, webhook jobs, notification jobs, search indexing jobs.
• Late stage: agent orchestration, workflow engine, multi-step recovery, human approval tasks.
• Depends on: observability, audit, contract schemas.
• Used by: webhooks, media-service, search-service, notifications, agents.
• Testing strategy: payload schema tests, retry tests, idempotency tests, dead letter tests, fake queue runtime.
• AI generation boundary: AI can add jobs only with idempotency key, retry/dead-letter behavior, and audit/trace hooks.
• Risks: duplicate side effects, lost jobs, runaway retries, hidden costs.

@prox-os/agents-runtime

• Purpose: agent registry, tool registry, MCP bridge, agent run model, tool call model, memory context, artifacts, rate limits, permission approval, audit log, human-in-the-loop gates.
• Non-goals: no permission bypass, no hardcoded prompt sprawl, no direct DB operation without audited tool.
• Early stage: agent run contract, tool call event model, permission requirements, no complex executor yet.
• Mid stage: tool registry, MCP connector model, run timeline, jobs integration, audit integration.
• Late stage: multi-agent workflows, business ops agents, code/data agents, user-owned memory, app-level agent marketplaces.
• Depends on: permissions, jobs, audit, observability, api-contract.
• Used by: AI apps, MCP Gateway, future workflow builders, app tools.
• Testing strategy: tool permission tests, run timeline fixtures, approval gate tests, fake tool registry, audit correlation tests.
• AI generation boundary: AI cannot create executable tools without permission manifest, audit events, fixtures, and human approval gates.
• Risks: destructive tool calls, prompt leakage, runaway agents, unbounded cost.

@prox-os/audit

• Purpose: audit event schema for actor, resource, action, app/tool/agent source, before/after summary, request ID, retention, and compliance export direction.
• Non-goals: no observability metrics, no notification delivery.
• Early stage: audit event vocabulary; API, permission, and agent events can reference it.
• Mid stage: DB audit table, query API, admin audit UI support, agent/action audit integration.
• Late stage: compliance exports, tamper-evident log direction, security anomaly detection.
• Depends on: db, observability.
• Used by: permissions, storage, billing, webhooks, agents, jobs.
• Testing strategy: event schema tests, snapshot tests, request correlation tests, retention policy fixtures.
• AI generation boundary: AI can add auditable actions only with actor/resource refs and before/after summary.
• Risks: missing critical events, sensitive payload logging, weak retention policy, compliance gaps.

@prox-os/billing

• Purpose: plans, subscriptions, one-time tips, sponsorships, invoices, payment provider events, entitlements, usage limits, billing audit events.
• Non-goals: no permission core, no notification delivery, no live payment provider before readiness.
• Early stage: pricing, plan, entitlement vocabulary aligned with Pricing and Tips UI; no Stripe integration yet.
• Mid stage: payment provider webhook handling, subscription lifecycle, entitlement checks, usage limits.
• Late stage: marketplace revenue sharing, app developer payouts, organization billing, regional tax/invoice complexity.
• Depends on: webhooks, audit, notifications-service, permissions.
• Used by: Pricing, Tips, App Store, entitlements, marketplace.
• Testing strategy: payment event replay, entitlement matrix tests, invoice ref fixtures, usage limit tests.
• AI generation boundary: AI cannot connect payment providers without webhook fixtures, replay tests, entitlement tests, and legal/payment readiness review.
• Risks: money movement bugs, entitlement drift, tax/invoice complexity, provider lock-in.

@prox-os/webhooks

• Purpose: inbound/outbound webhook endpoint contracts, signature verification, event normalization, idempotency, retry/dead-letter routing, event replay, webhook audit.
• Non-goals: no direct business side effects, no unsigned event processing.
• Early stage: webhook event envelope, signature verification policy, GitHub star, Stripe, Cloudflare, Grist event docs.
• Mid stage: inbound handlers, jobs integration, audit integration, event replay.
• Late stage: third-party app webhooks, outbound subscriptions, app marketplace integration.
• Depends on: api-contract, jobs, audit, observability.
• Used by: billing, badges, deployments, external connectors.
• Testing strategy: signature tests, fixture replay, idempotency tests, malformed payload tests.
• AI generation boundary: AI can add providers only with sample events, signature verifier, replay fixtures, and dead-letter behavior.
• Risks: forged events, duplicate processing, provider-specific drift, hidden side effects.

@prox-os/observability

• Purpose: logger interface, request ID, trace context, metrics helpers, error reporting hooks, agent run telemetry, audit correlation ID, OpenTelemetry direction, Cloudflare Analytics/Logpush/external provider direction.
• Non-goals: no audit replacement, no user notification delivery.
• Early stage: logger/metrics/trace contract, standard request ID, API error correlation.
• Mid stage: Hono middleware, jobs telemetry, agent run telemetry, search indexing telemetry.
• Late stage: OpenTelemetry export, incident dashboards, cost observability, per-app performance budgets.
• Depends on: none, except provider adapters.
• Used by: all backend packages.
• Testing strategy: logger mocks, request ID propagation tests, trace context tests, error correlation snapshots.
• AI generation boundary: AI can add instrumentation only through package interfaces, not direct provider SDK scatter.
• Risks: noisy logs, sensitive data logging, missing correlation, vendor lock-in.