Files

Architecture Governance / architecture (push) Has been cancelled

Details

fix: install shared packages over git, unbreaking CI

The Verdaccio registry introduced earlier is unreachable from CI (listens on
127.0.0.1:4873 behind a firewall allowing only 80/443/SSH), which broke the
architecture-governance workflow - its npm ci step could no longer resolve
@marketplaces/auth.

Packages are now published to git release branches (release/auth,
release/payment in vitanovaPackages) whose root is the package itself, and
installed with git+<repo>#release/auth. No registry, token, tunnel, or CI
secret - anonymous git read is enough.

- package.json: git dependency; .npmrc removed (no scope mapping needed)
- vitanovaPackages release.yml rebuilt to force-push release branches
- ADR-0001 amended with the distribution change and why the registry lost
- BACKEND-HANDOFF: added the multi-tenancy section (hostname -> tenantKey ->
  per-tenant bootstrap config), corrected the install and deploy notes, and
  recorded that no CD pipeline exists
- PACKAGE-EXTRACTION / PACKAGES-USAGE rewritten for the git-branch flow

Verified: npm ci, arch:check:boundaries, ng build, 103/103 tests, all with
no credentials configured.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-18 02:08:05 +04:00

4.5 KiB

Raw Blame History

id, title, status, date, supersedes, tags

title

status

date

supersedes

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 and Phase 7 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 TRACK-S-SECURITY-RBAC-CONTRACT.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:

Lives in its own git repo (handed over separately; this repo does not host it long-term).
Is consumed by marketplaces (and other projects) as an installed node_modules dependency — imported, never copy-pasted.
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).
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.
TRACK-S-SECURITY-RBAC-CONTRACT.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.

4.5 KiB Raw Blame History