Backend Package Graph

This document maps the future backend package graph. It is an architecture map, not an implementation status report.

Layer Graph

graph TD
  subgraph API["API Foundation"]
    ApiContract["@prox-os/api-contract"]
    ApiKit["@prox-os/api-kit"]
    Observability["@prox-os/observability"]
  end

  subgraph Data["Data Foundation"]
    Db["@prox-os/db"]
    Search["@prox-os/search-service"]
    Audit["@prox-os/audit"]
  end

  subgraph Identity["Identity & Permissions"]
    Auth["@prox-os/auth"]
    Permissions["@prox-os/permissions"]
  end

  subgraph Storage["Storage & Media"]
    StoragePkg["@prox-os/storage"]
    MediaService["@prox-os/media-service"]
  end

  subgraph Automation["Automation & Integration"]
    Jobs["@prox-os/jobs"]
    Webhooks["@prox-os/webhooks"]
    Agents["@prox-os/agents-runtime"]
  end

  subgraph Business["Business & Notifications"]
    Billing["@prox-os/billing"]
    Notifications["@prox-os/notifications-service"]
  end

  ApiContract --> ApiKit
  Observability --> ApiKit
  ApiKit --> Auth
  ApiKit --> Permissions
  Auth --> Db
  Permissions --> Db
  Permissions --> Audit
  StoragePkg --> Permissions
  StoragePkg --> Audit
  MediaService --> StoragePkg
  MediaService --> Jobs
  Search --> Db
  Search --> Permissions
  Webhooks --> Jobs
  Jobs --> Observability
  Agents --> Permissions
  Agents --> Jobs
  Agents --> Audit
  Billing --> Webhooks
  Billing --> Audit
  Billing --> Notifications
  Notifications --> Jobs
  Notifications --> Audit

Core Dependency Graph

graph LR
  ApiContract["@prox-os/api-contract"] --> ApiKit["@prox-os/api-kit"]
  Observability["@prox-os/observability"] --> ApiKit
  Auth["@prox-os/auth"] --> ApiKit
  Permissions["@prox-os/permissions"] --> ApiKit

  Db["@prox-os/db"] --> Auth
  Db --> Permissions
  Audit["@prox-os/audit"] --> Permissions
  Audit --> Storage["@prox-os/storage"]
  Observability --> Storage
  Permissions --> Storage

  Storage --> MediaService["@prox-os/media-service"]
  Jobs["@prox-os/jobs"] --> MediaService
  Audit --> MediaService

  Permissions --> Agents["@prox-os/agents-runtime"]
  Jobs --> Agents
  Audit --> Agents
  Observability --> Agents

  Webhooks["@prox-os/webhooks"] --> Billing["@prox-os/billing"]
  Audit --> Billing
  Notifications["@prox-os/notifications-service"] --> Billing

Interpretation:

api-kit depends on api-contract, observability, auth, and permissions.
auth depends on db and observability.
permissions depends on db and audit.
storage depends on permissions, audit, and observability.
media-service depends on storage, jobs, and audit.
agents-runtime depends on permissions, jobs, audit, and observability.
billing depends on webhooks, audit, and notifications-service.

Event Flow Graph

graph TD
  ExternalWebhook[External webhook] --> Webhooks["@prox-os/webhooks"]
  Webhooks --> Jobs["@prox-os/jobs"]
  Jobs --> DomainService[Domain service package]
  DomainService --> Audit["@prox-os/audit"]
  DomainService --> Notifications["@prox-os/notifications-service"]
  DomainService --> Observability["@prox-os/observability"]

  AgentRun[Agent run] --> Agents["@prox-os/agents-runtime"]
  Agents --> AgentJobs["@prox-os/jobs"]
  AgentJobs --> Tools[Tool call]
  Tools --> Permissions["@prox-os/permissions"]
  Permissions --> AgentAudit["@prox-os/audit"]
  Tools --> Artifacts[Artifacts and app data]

  BillingWebhook[Billing webhook] --> BillingEvents["@prox-os/webhooks"]
  BillingEvents --> BillingJobs["@prox-os/jobs"]
  BillingJobs --> Billing["@prox-os/billing"]
  Billing --> Entitlements[Entitlements]
  Billing --> BillingNotifications["@prox-os/notifications-service"]
  Billing --> BillingAudit["@prox-os/audit"]

Cloudflare-first Runtime Direction

Concern	Preferred future runtime
HTTP API	Cloudflare Workers + Hono
OpenAPI	`@prox-os/api-contract` + generated docs/client
PostgreSQL	Neon/Postgres through `@prox-os/db`
Object storage	Cloudflare R2 through `@prox-os/storage`
Async jobs	Cloudflare Queues, Cron Triggers, and future Workflows
Media transforms	Cloudflare Images / Image Transformations / Workers
Observability	Request IDs, structured logs, metrics, traces, Cloudflare Analytics/Logpush, and OpenTelemetry direction
Agents	Permissioned tool calls, jobs, audit, and MCP bridge

Start Order

api-contract, api-kit, observability.
db.
auth, permissions, audit.
One pilot domain package path: media, moments, dreams, or billing.
jobs, webhooks, search-service, notifications-service.
agents-runtime, billing, marketplace extensions.

Backend Package Graph

Layer Graph

Core Dependency Graph

Event Flow Graph

Cloudflare-first Runtime Direction

Start Order

On this page