Digital Walls — system architecture (current state)

This document describes how the application is built and deployed today. It is not a product roadmap, security audit, or operations runbook. For deploy procedures and backups, see BACKEND_OPERATIONS.md. For auth setup, see SUPABASE_AUTH.md. For UX behavior, see FRONTEND_FLOWS.md. For create/read/update/delete per table, see DATA_FLOWS.md.

The aspirational data model in DATA_MODEL.md is older reference material; executable schema lives under server/migrations/ (SQLite) and server/migrations/postgres/ (Postgres).

---

1. Deploy topology

Hosting targets

Vercel configuration is in vercel.json:

• Build: npm ci, then node scripts/prepare-studio.mjs (studio catalog).
• Runtime: One Node build on server.js with public/**, server/**, and sharp bundled.
• Routing: All paths /(.*) → /server.js (API and HTML shell). Output Directory in the Vercel project must stay empty so the Node entry is not replaced by static-only hosting.

Browser assets live in `public/` (HTML, JS, CSS, static sprites). That separation keeps client bundles out of the serverless entry and allows the CDN to serve static files where configured. The Node handler still serves public/ for local and Docker runs.

There is no root Dockerfile for Vercel Git deploys (only docker/Dockerfile) to avoid accidental Container Registry deploys.

Supabase integration

Connecting the Vercel Supabase integration typically sets SUPABASE_URL, publishable/anon key, and POSTGRES_URL. The app does not use a Supabase service-role key at runtime.

Postgres connection pooling

server/runtime-config.js resolves the database URL:

• On Vercel, prefers DATABASE_URL, then POSTGRES_URL, then POSTGRES_URL_NON_POOLING, each normalized through sessionPoolerUrl().
• Supabase transaction pooler URLs (:6543 on pooler.supabase.com) are rewritten to session pooler port `:5432` for serverless compatibility.
• Local / Docker can use non-pooling URLs for CLI or direct connections; migrations for Postgres run from app boot via PostgresStore.migrate().

There is no Prisma in this repository; ignore Prisma-related env vars unless some external tooling sets them.

High-level topology

                    ┌─────────────────────────────────────┐
                    │           Browser                   │
                    │  public/*.js, explore.html, etc.    │
                    └─────────────────┬───────────────────┘
                                      │ HTTPS
                    ┌─────────────────▼───────────────────┐
                    │  Vercel (@vercel/node) or Node host │
                    │  server.js → createApp()            │
                    └─────┬───────────────────┬───────────┘
                          │                   │
              ┌───────────▼──────────┐   ┌────▼──────────────┐
              │ Supabase Auth (REST) │   │ PostgresStore or  │
              │ signup/login/reset   │   │ SqliteStore       │
              └──────────────────────┘   └────┬──────────────┘
                                              │
                                    Supabase Postgres (hosted)
                                    or local SQLite file

---

2. Request flow

Pages and routing

The HTTP server (server/server.js) handles:

1. **/api/* — JSON API (auth, boards, assets, explore, health). 2. /studio, /studio-library/* — Internal studio tooling (`server/studio.js`). 3. Static allowlist** — HTML/JS/CSS under public/, plus /assets/* and curated paths. Database paths, .env, and repo internals are not served.

HTML entry mapping (examples):

Share links use /?board=<share_token> (opaque token on boards.share_token).

API surface (summary)

Mutating request guards

Non-GET requests require:

• Allowed Origin (configured origin or actual request host on Vercel),
• Sec-Fetch-Site not cross-site,
• Header X-Wall-Request: 1 (set by client JS).

Production responses add HSTS and a restrictive Content-Security-Policy.

Typical flows

Guest → account → save

Browser (guest.js local draft)
  → POST /api/signup (Supabase Auth + app user row)
  → Session cookie
  → PUT /api/boards/:id (claim/sync wall state)
  → Postgres or SQLite persists boards + assets

Owner edit with autosave

wall.js → PUT /api/boards/:id { revision, items, settings, ... }
  → walls.save() validates + transaction
  → revision increment or 409 Conflict

Public explore

explore.js → GET /api/explore?sort=votes|recent
  → boards where visibility = public
  → optional POST/DELETE vote (signed-in user only)

Shared link view (no account)

GET /?board=<share_token> → GET /api/boards/<token> (read)
  → walls.access() enforces private vs shared/public
  → GET /api/assets/:id for images when allowed

Authorization rules (private owner session vs link-based read) are implemented in `walls.js`, `uploads.js`, and `accounts.js`, not in Supabase RLS.

---

3. Data model (implemented)

Migrations apply automatically on startup:

• SQLite: server/migrations/*.sql tracked in table migrations.
• Postgres: server/migrations/postgres/*.sql tracked in schema_migrations (advisory lock on migrate).

Core tables

Storage abstraction

openStore() in server/database.js returns either:

• `SqliteStore` — serialized writes via queue; WAL mode locally.
• `PostgresStore` — postgres driver, max: 1 connection per serverless instance, prepare: false, migrations on boot.

Both stores expose the same async API (get, all, run, transaction) so domain modules stay storage-agnostic.

What is not in the database

• Guest drafts before signup: kept in browser storage (guest.js) until claimed.
• Catalog sprites under public/assets/: shipped as static files, not per-user DB rows.

---

4. Environments and configuration

Behavior is driven by resolveRuntimeConfig() (server/runtime-config.js) and environment variables. See .env.example for a template; the server does not auto-load .env files in production.

Runtime matrix

On Vercel, if Postgres or Supabase is missing, the app still serves guest/explore static flows and logs warnings at boot; account-backed saves return 503 rather than writing to ephemeral disk.

Environment variables (meaningful today)

Scripts only (not runtime app): SUPABASE_ACCESS_TOKEN, SUPABASE_SERVICE_ROLE_KEY, test account vars — see AGENT_TEST_ACCOUNT.md.

Git and deployment

• Version control: GitHub (adamsloane/digitalwalls).
• Deploy: Vercel Git integration (project settings + vercel.json).
• CI in repo: No .github/workflows in this checkout; validation is via local/ agent runs of npm run check, npm test, and npm run test:e2e (Playwright).

---

5. Open questions (not decided in code/docs)

These are intentional TBDs for product/ops; the system above reflects what is implemented regardless.

---

6. Related documents