sdarbinyan/marketplaces
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: backend handoff, package usage guide, finalized CI/CD
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
Details

Browse Source 
- docs/backend/BACKEND-HANDOFF.md: single entry point for a backend dev -
  reading order, verified infrastructure state (nginx running, Postgres
  inactive, no API on :8080, no TLS, no DNS automation, no CI runner),
  auth surface, and the day-one setup that is still outstanding
- docs/PACKAGES-USAGE.md: install, required DI providers, full exported
  API for both auth mechanisms, and how to ship a package change
- PACKAGE-EXTRACTION.md now covers build/release/infra only and points at
  the usage guide; CI section reflects the two real workflows

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
sdarbinyan
2026-08-18 01:46:58 +04:00
parent 2e4bb4ae00
commit f6045a07b2
4 changed files with 222 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/backend/BACKEND-HANDOFF.md Normal file
View File

@@ -0,0 +1,69 @@
# 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](README.md) for the full index and build order.
## 2. Read in this order
1. [README.md](README.md) — index of all contracts, build order, and what's deliberately excluded.
2. [PHASE-1-MONEY-FX-PAYMENTS-CONTRACT.md](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](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](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](../../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](https://sources.vitanova.network/sdarbinyan/vitanovaPackages.git). See [../PACKAGES-USAGE.md](../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](TRACK-S-SECURITY-RBAC-CONTRACT.md) 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](PHASE-9-TENANT-REGISTRY-DOMAINS-CONTRACT.md) 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](TRACK-S-SECURITY-RBAC-CONTRACT.md)) — frontend route guards derive from it.
6. Seed per-marketplace bootstrap admins ([TRACK-S §8](TRACK-S-SECURITY-RBAC-CONTRACT.md)): 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](../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](PHASE-7-PAYMENTS-RECONCILIATION-CONTRACT.md).
- Per-connector marketplace adapters — written per partner at onboarding, [Phase 4 §8](PHASE-4-CONNECTOR-FRAMEWORK-CONTRACT.md).

2
docs/backend/README.md
View File

@@ -1,5 +1,7 @@
# Backend Contracts Index — Product Plan v3.1
> **New here? Start with [BACKEND-HANDOFF.md](BACKEND-HANDOFF.md)** — reading order, current infrastructure state, auth surface, and what a working dev environment still needs.
This directory is the complete set of wire contracts for building the backend behind [Product Plan v3.1](../PRODUCT-PLAN-v3.1-GAP-ANALYSIS.md). Each doc specifies entities, endpoints, and invariants only — never DB schema or service boundaries, which stay backend's own call.
**Read order matches build order.** Every doc after Phase 1 depends on the ones before it (noted at the top of each). All Sprint 0.1 decisions referenced throughout were answered 2026-08-17 — see [PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md](../PRODUCT-PLAN-v3.1-DELIVERY-PLAN.md) Sprint 0.1 for the full record.