Architecture documentation & production-readiness plan

Status: ARCHITECTURE.md drafted (sections 1–4 + open questions). Phase 1 audit not started. Audience: Adam (owner), primary coding agent, future contributors. Repo: Digital Walls (digital-sanctuary-mvp) — Vercel + Supabase + GitHub.

---

Goal

1. Capture current-state architecture in a single canonical doc (docs/ARCHITECTURE.md) without mixing audit findings, risks, or roadmap. 2. Execute Adam’s four-phase production-readiness program using separate, linked documents. 3. Reuse and reconcile existing docs under docs/ instead of duplicating them.

---

Document map (keep ARCHITECTURE.md clean)

Existing docs — role after this work

---

docs/ARCHITECTURE.md outline (first sections to write)

These sections match Digital Walls’ actual stack and pay off immediately for onboarding and deploy debugging.

1. Deploy topology

• Vercel: @vercel/node handler from root server.js; vercel.json routes /(.*) → server.js; build runs scripts/prepare-studio.mjs.
• Static vs compute: Browser assets in public/ (CDN-friendly); API + HTML shell served by Node handler.
• Alternative: Self-hosted Docker (docker/Dockerfile) — long-lived Node + SQLite on /data (not Vercel path).
• Supabase: Auth (REST via server/supabase-auth.js); Postgres for durable data on Vercel; no Supabase Storage for wall images today (bytes in DB).
• Postgres connectivity: resolveDatabaseUrl() — transaction pooler :6543 upgraded to session pooler :5432 on Vercel; direct/non-pooling for local CLI migrations only.
• Ephemeral Vercel disk: /tmp/digital-walls.sqlite only when Postgres unset; account routes 503 — guest mode still works.

2. Request flow

ASCII or mermaid diagram:

Browser (public/*.js, HTML)
  → Vercel → server.js → createApp (server/server.js)
  → Accounts (Supabase session cookies) | Walls | Discover | Uploads
  → openStore → PostgresStore | SqliteStore

Cover: CSRF-ish guards (Origin, Sec-Fetch-Site, X-Wall-Request), session cookie, share-token read paths, explore/votes (Discover).

3. Data model (implemented)

• Source of truth: server/migrations/ (SQLite) and server/migrations/postgres/ (Postgres).
• Core entities: users (+ supabase_id), sessions, boards, board_items, image blobs, explore/votes tables from 003_* / postgres 002_*.
• Explicit note: authorization is application-layer, not Supabase RLS (Postgres is accessed with server credentials only).

4. Environments

Env vars that matter: APP_ORIGIN, SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, POSTGRES_URL / DATABASE_URL, NODE_ENV, PORT, DATABASE_PATH (non-Vercel).

Safe to ignore (unless tooling): Prisma-style URLs if present in dashboard but unused; SUPABASE_ACCESS_TOKEN (scripts only); service role (test scripts only).

---

Phase alignment (Adam’s email)

Phase 1 — Audit (docs/PRODUCTION_AUDIT.md)

Structured passes; each finding: severity (S0–S3), effort (S/M/L), evidence (file/link).

Deliverable: ranked findings table + “accepted risks” section for product sign-off.

Phase 2 — Production standard (docs/PRODUCTION_STANDARD.md)

Lightweight defaults (prefer existing tools):

• PR + feature branch for meaningful changes (cursor/*-b53f pattern for agents).
• CI: npm run check, npm test, optional e2e on main/PR.
• Migrations: versioned SQL in server/migrations/postgres/ applied on boot; add explicit “migration review” rule.
• AuthZ: document app-layer rules; decide whether Supabase RLS is in scope or explicitly out of scope for v1.
• No silent production changes without approval (already in agent instructions).

Phase 3 — Engineering rules

• .cursor/rules/production.mdc (or split by concern): PRs, migrations, RLS verification when added, tests, minimal diffs, error handling, task summary template.
• docs/ENGINEERING_RULES.md: same content in prose for non-Cursor readers.

Phase 4 — Safeguards (incremental, after approval)

Examples (not started in plan mode):

• GitHub Actions workflow for check + unit tests.
• Health/version endpoints already exist — document alerting hooks.
• Supabase auth URL script + template sync documented in CI optional job.
• Explicitly out of bounds without approval: prod data changes, destructive migrations, credential rotation, Vercel prod config changes.

Final: `docs/OPERATIONS_CHECKLIST.md` — configured / manual / outstanding.

---

Execution order (recommended)

flowchart LR
  A[Plan sign-off] --> B[ARCHITECTURE.md draft]
  B --> C[Phase 1 audit doc]
  C --> D[Review findings with Adam]
  D --> E[PRODUCTION_STANDARD.md]
  E --> F[ENGINEERING_RULES + Cursor rules]
  F --> G[Approved Phase 4 items]
  G --> H[OPERATIONS_CHECKLIST.md]

1. Sign off this plan (scope, doc names, RLS in/out of scope). 2. Draft `ARCHITECTURE.md` from code + existing ops docs (~1 focused pass). 3. Parallel audit workstreams into PRODUCTION_AUDIT.md (can split by agent/thread). 4. Review → standard → rules → implement approved safeguards.

---

Open decisions (need product/engineering alignment)

1. Supabase RLS & Storage: MVP checklist still lists RLS/storage as open; app today uses server-side Postgres with app auth. Standard path: document as intentional for v1, or plan RLS migration? 2. Canonical production host: Vercel production URL vs custom domain — drives APP_ORIGIN and Supabase redirect URLs. 3. CI scope: Unit tests only on every PR vs full Playwright (slower, flakier). 4. Docker vs Vercel: Is Docker a supported production target alongside Vercel, or dev/self-host only?

---

Success criteria

• New engineer can read `ARCHITECTURE.md` and explain deploy topology, one API save path, and env vars in <30 minutes.
• `PRODUCTION_AUDIT.md` has a ranked list with no “unknown” for auth, data store, or deploy entrypoint.
• Phase 3 rules exist in repo and match how the agent already works on Cloud Agents.
• Phase 4 checklist is honest about manual Supabase/Vercel dashboard steps.

---

Next step (after you choose)

Recommended: D — architecture doc first (~half day of agent time), then audit with stable vocabulary.