d44565fae9
Some checks failed
Architecture Governance / architecture (push) Has been cancelled
Collapses the entire docs/backend/ set - Phase 1-10, Track A/S, the partner API, the two handoffs, the frontend surface inventory, and the harvest requirements - into a single source of truth, docs/backend/BACKEND-INTEGRATION.md. Every contract's entities, endpoints, and invariants are preserved, reorganised by domain rather than by sprint. The nine release invariants, the FH-* harvest mechanisms, the RBAC/audit/secrets cross-cutting rules, the tenant-routing infra contract, the 15 acceptance tests, build order, dev setup, and open decisions are all in the one file, with a change log (§14) at the bottom. The file opens with the maintenance rule: any new backend need, contract change, or shipped item updates this file in the same change - the affected section and the change log. No new backend .md files. Inbound links from BACKEND-API-REFERENCE, the ADRs, the fork docs, DEPLOYMENT, PACKAGES-USAGE, the delivery plan, and e2e/README are repointed at the single doc (section anchors collapse to the file; the prose section refs remain as context). Also recorded the rule in the repo CLAUDE.md. 17 backend docs removed, 1 added. No implementation changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
47 lines
4.5 KiB
Markdown
47 lines
4.5 KiB
Markdown
---
|
|
id: ADR-0001
|
|
title: Extract auth and payment into shared @marketplaces packages
|
|
status: active
|
|
date: 2026-08-17
|
|
supersedes: []
|
|
tags: [architecture, auth, payment, monorepo]
|
|
---
|
|
|
|
# ADR-0001: Extract auth and payment into shared @marketplaces packages
|
|
|
|
## Context
|
|
|
|
`marketplaces` currently owns auth end-to-end: customer auth (`core/auth` — VK ID, OTP, session, facade), admin auth (`core/admin-auth` — ed25519-verified admin sessions, permission guards, interceptor), and a legacy `services/auth.service.ts`. Payment/finance logic (`core/finance`, `core/pricing`) is server-owned per [Phase 1](../../backend/BACKEND-INTEGRATION.md) and [Phase 7](../../backend/BACKEND-INTEGRATION.md) contracts — the frontend piece is thin (gateways/tokens, no business logic).
|
|
|
|
Multiple marketplace projects beyond this repo need the same auth and payment client logic. Duplicating it per-project drifts fast (auth bugs get fixed in one place, not others) and blocks a consistent security posture across projects — directly relevant to [../../backend/BACKEND-INTEGRATION.md](../../backend/BACKEND-INTEGRATION.md), which already treats auth/RBAC as the single most serious cross-cutting concern.
|
|
|
|
## Decision
|
|
|
|
Extract auth and payment client logic into two standalone, independently versioned npm packages:
|
|
|
|
- `@marketplaces/auth` — customer auth (VK ID/OTP/session), admin auth (ed25519 verification, permission guards, interceptors), token/session management.
|
|
- `@marketplaces/payment` — payment/finance client gateways, FX/pricing models, checkout client contracts (thin — business logic stays backend per Phase 1/7).
|
|
|
|
Each package:
|
|
1. Lives in its own git repo (handed over separately; this repo does not host it long-term).
|
|
2. Is consumed by `marketplaces` (and other projects) as an installed node_modules dependency — imported, never copy-pasted.
|
|
3. Is versioned with semver; CI on the package repo auto-bumps and publishes on push to `main`, driven by conventional commit prefixes already used in this repo (`feat:`/`fix:`/etc — semantic-release reads these directly).
|
|
4. Ships with its own test suite; `marketplaces` treats it as a black-box dependency, not source to edit in place.
|
|
|
|
Rollout order: scaffold packages and CI in this repo first (reversible, local-only) → hand over target git repo → publish → migrate `marketplaces` call sites to import from the package → delete the in-repo originals only after the app builds and passes tests against the package.
|
|
|
|
## Amendment 2026-08-18 — distribution mechanism
|
|
|
|
The original decision left distribution open ("private registry ... or installed straight from git"). A private Verdaccio registry was stood up on the dev server and both packages published to it. **That approach was then abandoned**: the registry listens on `127.0.0.1:4873` behind a firewall allowing only 80/443/SSH, so neither CI runners nor developers could install without an SSH tunnel. That broke `marketplaces`' existing `architecture-governance` workflow, whose `npm ci` step could no longer resolve `@marketplaces/auth`.
|
|
|
|
Distribution is now **git release branches**: `release/auth` and `release/payment` in vitanovaPackages, each an orphan branch whose root *is* the package (`package.json` + built `dist/`), force-pushed by CI on every release. Consumers install with `git+<repo>#release/auth` — no registry, no token, no tunnel, no CI secret; anonymous git read suffices.
|
|
|
|
The Verdaccio instance still runs but nothing depends on it. Making a registry the primary path again would require a reverse proxy plus TLS on the dev server, which buys nothing over the current approach at this scale.
|
|
|
|
## Consequences
|
|
|
|
- `marketplaces` loses direct edit access to auth/payment source — changes go through the package's own repo/PR/release cycle. Slower iteration, but consistent behavior across all consuming projects.
|
|
- ~30 call sites in `marketplaces` (see `core/auth`, `core/admin-auth`, `services/auth.service.ts`, interceptors) need import rewiring during migration — tracked as follow-up work, not done in this ADR.
|
|
- New failure mode: `marketplaces` builds now depend on `sources.vitanova.network` being reachable. A branch ref also tracks its tip, so an install can pick up a new build — acceptable while the package churns, but pin to a commit SHA once it stabilises.
|
|
- [../../backend/BACKEND-INTEGRATION.md](../../backend/BACKEND-INTEGRATION.md) §8 (admin provisioning) becomes package-owned behavior once migrated — that doc's endpoint contracts stay backend-side and unaffected, only the frontend client implementation moves.
|