Backend Foundation v0

Goal

Backend Foundation v0 turns the backend from a scary black box into a visible, reversible, testable system. It serves the solo builder first before it serves external developers.

This foundation does not try to clone Neon, Scalar, Web3Forms, Cloudflare, GitHub, Notion, Airtable, Google, Figma, PostHog, or Sentry. Prox OS starts as a navigation, context, progress, and workflow layer around those tools. The first backend-facing OS surface is the lightweight Backend Foundation app at /app-admin/backend, not a full backend platform.

The current pass is UI, documentation, static mock data, and external console links. It does not add authentication, SQL execution, OAuth, connector token storage, queues, background jobs, production database writes, or provider API calls.

Vertical Slice Development Model

Every backend capability should move through a small vertical slice sequence:

1. Product question
2. UI states
3. Mock scenario
4. API contract
5. Hono route
6. Service layer
7. Database schema or migration only when necessary
8. Tests
9. Docs
10. Observability notes
11. Rollback notes

Early Prox OS backend work should not start with database tables. Start with the product question, then UI states, mock scenarios, and contracts. A database schema is introduced only when the slice has a narrow purpose, visible user state, reviewed contracts, and rollback notes.

AI Async Multi-Branch Safety Model

Parallel AI or CodeX work should keep backend risk serialized:

• Contract branches land first.
• Mock branches land after or alongside contracts.
• UI branches can move faster because they should stay static or mock-backed.
• Real API branches should be smaller and reviewed more carefully.
• Database schema branches must be serialized or explicitly coordinated.
• Multiple branches must not modify schema, environment files, Wrangler config, root package scripts, or app registry core at the same time without explicit coordination.
• One migration owner coordinates database schema work at a time.

Recommended branch names:

• docs/backend-foundation-v0
• ui/admin-backend-app
• ui/admin-connector-sandbox
• ui/admin-mock-lab
• contract/waitlist-v0
• mock/waitlist-scenarios
• be/waitlist-route
• db/waitlist-schema
• qa/waitlist-integration

Recommended First Backend Slices

The recommended order for real backend work is:

1. Early Access / Waitlist
2. App Registry read API
3. Feedback / Bug Report
4. AI Question Tracker
5. Auth foundation
6. R2 upload prototype
7. Moments v0

Moments should not be the first real backend slice. It combines auth, privacy, object storage, EXIF, thumbnails, search, batch import, CDN behavior, and potentially user-owned media lifecycle decisions. Those concerns should be proven in smaller slices first.

External Console First Policy

Prox OS should use external consoles first and aggregate context, status, links, and operating notes. It should not replace these tools in early backend work:

• Scalar API reference
• Cloudflare Workers, Pages, Logs, Access, and R2
• Neon Console
• Web3Forms Dashboard
• GitHub Actions, Issues, and Pull Requests
• PostHog and Sentry if added later
• Notion Developers
• Airtable Developers
• Google Cloud Console
• Figma Developers

External consoles remain the source of truth for operations until Prox OS has small reviewed contracts and safe read-only summaries.

Admin vs Dev App Boundary

/app-admin is for future online OS administration: real data, operations, users, tenants, waitlist, feedback, audit, permissions, billing, jobs, storage, admin review queues, and production readiness.

/app-dev is for local development: API docs, contracts, mock scenarios, Storybook, Scalar, local tools, test scenarios, external developer consoles, debugging, architecture graphs, and route maps.

This split is not a security boundary. It is an early product and information architecture boundary. Real access control must later come from authentication, permissions, deployment environment, Cloudflare Access, and backend policy.

Backend Foundation Apps

/app-admin/backend is the Backend Foundation app. It shows current backend resources, external console entries, the vertical slice roadmap, and safety rules. It includes Early Access / Waitlist as an external Web3Forms-backed capability and links to Scalar, Cloudflare, Neon, GitHub, App Map, Mock Lab, and the existing Operations & Observability Hub.

/app-admin/connector-sandbox is the Connector Sandbox app. It is a mock-only laboratory for understanding providers, permissions, payload shapes, and failure modes. It is not the Data API Transit Hub.

The future Data API Transit Hub is a backend runtime boundary for hiding secrets, normalizing provider data, applying permissions, caching, rate limiting, audit logging, and stable connector contracts. Backend Foundation v0 does not modify or implement that runtime.

/app-admin/mock-lab is the Mock Lab app. It tracks UI state coverage, mock scenario coverage, contract readiness, real API migration, DB readiness, docs, and next steps. It is a progress map, not a test runner replacement.

Mock Lab remains in /app-admin for this foundation pass because the admin workspace needs a visible backend-readiness board. It can later receive a secondary /app-dev entry if scenario toggles, MSW adapters, or local-only debug controls become the main workflow.

Why iframe and external links first

Iframe entries and external links are safer than copying whole consoles into Prox OS. They let the shell provide navigation, context, status, and fallback commands while the external product keeps responsibility for credentials, runtime logs, database administration, API references, deploy operations, and provider security.

If an external surface refuses iframe embedding, the shell should keep using the existing managed fallback pattern: open in OS when possible, open in a new tab when required, and keep the link copyable.