marketplaces/docs/backend/BACKEND-HANDOFF.md

Backend handoff — start here

Single entry point for a backend developer picking this up cold. Written 2026-08-18.

1. What this is

marketplaces is a multi-tenant marketplace platform frontend (Angular 22). The frontend is built and waiting; there is no backend yet. Every wire contract the backend needs to implement is already written and sitting in this directory — see README.md for the full index and build order.

2. Read in this order

1. README.md — index of all contracts, build order, and what's deliberately excluded.
2. PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md — start here. Everything after depends on the money model.
3. Phases 2→4 — the rest of the launch gate (orders, catalog, connectors).
4. TRACK-S-SECURITY-RBAC-CONTRACT.md — gates the launch. Today the admin role model is decorative: nothing server-side enforces any permission. §8 covers per-marketplace bootstrap admin accounts and self-service sub-admin management.
5. TRACK-A-ANALYTICS-CONTRACT.md — longest lead time, start it in parallel with Phase 1.
6. Phases 5→10 — post-launch-gate.

../../BACKEND-API-REFERENCE.md documents the current live API surface (legacy endpoints, error envelope, mock-only areas). New endpoints use /api/v2/... namespaces; legacy endpoints are not being migrated.

3. Auth — read before writing any endpoint

Auth is no longer part of this repo. It lives in @marketplaces/auth, published from vitanovaPackages. See ../PACKAGES-USAGE.md for the full client surface. What matters on the backend side:

Two mechanisms exist client-side.

• Telegram QR/session (live). Endpoints under {authApiUrl}/users/sessions — POST to create, GET /{id} to poll, DELETE /{id} to log out. Both customer and admin login call the same endpoints; only client-side storage differs. The response shape is normalized permissively client-side (many key spellings accepted), but a clean implementation should return { webSessionID, user: { userId, username, firstName, lastName }, status, expiresAt }.
• Ed25519 challenge/response (not built). GET /api/admin/auth/challenge, POST /api/admin/auth/verify, POST /api/admin/auth/refresh, POST /api/admin/auth/logout. Contracts in TRACK-S and the package's ed25519/models/auth-api.model.ts. Until these ship, the client shows a backend-unavailable screen — nothing is mocked.

The critical gap: the session API has no concept of "admin." The frontend cannot distinguish an admin session from a customer one — it only chooses where to store the result. Every admin endpoint must independently verify authorization server-side. Client-side guards are UI convenience, never security. This is the single most serious open issue in the system.

Admin requests carry AdminWebSessionID: <sessionId> (and Authorization: Bearer <token> once admin JWTs exist) on paths containing /admin/, /backoffice/, /builder/, /media/.

4. Environment / infrastructure state

Dev server 213.21.246.138 (user seto, sudo, SSH key provided separately).

Thing	State
nginx 1.24	Installed, running. Config at /etc/nginx/sites-enabled/marketplaces-dev.conf. Serves frontend from /srv/marketplaces/current/frontend, backoffice from /srv/marketplaces/current/backoffice, proxies /api/ → 127.0.0.1:8080. /health returns ok.
Go toolchain	Installed (/usr/local/bin/go).
Backend service on :8080	Not running. Nothing is listening. /srv/marketplaces/current/api is an empty shell. nginx's /api/ proxy currently 502s.
PostgreSQL	Installed but inactive. Needs starting, a database, a user, and schema before anything works.
Verdaccio (npm registry)	Running in Docker, port 4873, storage /srv/marketplaces/verdaccio/. Hosts @marketplaces/auth@0.1.0 and @marketplaces/payment@0.1.0. Only reachable from the server itself or via SSH tunnel — the firewall allows 80/443/SSH only.
Firewall (ufw)	Active. 80/tcp, 443/tcp, OpenSSH.
TLS / certbot	Not installed. No certificates. Everything is plain HTTP today.
DNS / dynamic subdomains	Not set up. The server has no domain pointed at it (reverse DNS is the provider default silky-bronze.ptr.network). There is no wildcard record, no per-tenant subdomain automation, and no Hostinger DNS integration. PHASE-9 specifies what this should become — none of it exists yet.
CI runner	None on this server. sources.vitanova.network CI runs elsewhere and currently cannot reach the Verdaccio registry.

5. To get a working dev environment

Nothing here is done yet — this is the setup a backend dev does on day one.

1. Start and configure PostgreSQL; create the database and application user.
2. Design the schema from the Phase 1–4 contracts (schema design is explicitly the backend's own call — the contracts specify entities, endpoints, and invariants, never tables).
3. Build the API service, listen on 127.0.0.1:8080. nginx already proxies /api/ to it.
4. Implement the Telegram session endpoints first — the frontend's login flow is fully built and blocked only on these.
5. Implement GET /api/identity/v1/session/permissions (TRACK-S §2) — frontend route guards derive from it.
6. Seed per-marketplace bootstrap admins (TRACK-S §8): login = marketplace slug, password = {slug}2026$, mustChangePassword: true.

6. Frontend deploy

The frontend builds with npm run build (Angular 22, Node 20+). Output goes to dist/dexarmarket, which is what nginx serves from /srv/marketplaces/current/frontend. Building it requires registry access for @marketplaces/auth — see ../PACKAGES-USAGE.md §1. A fresh npm install on a machine without a registry token will fail. That is the first thing to fix for anyone new joining.

7. Known open decisions

• Registry reachability for CI (reverse proxy + TLS, or a different registry entirely).
• Backend ownership was still unnamed as of Sprint 0.1.
• Additional payment providers (wallets, BNPL) — Phase 7 §4.
• Per-connector marketplace adapters — written per partner at onboarding, Phase 4 §8.