Last updated 2026-05-03

Life Connect ADB — wiki index

AI-generated content

This site is the human + agent entry point for everything we know about the hlc-lifeconnect/adb monorepo. The pattern, conventions, and ingest workflow are described in the repo-root AGENTS.md. Pages are auto-flagged with their kind and status; if you find one that's stale, file an issue or edit it directly.

How this is organised

docs/
├── architecture/   concepts: how the whole thing fits together
├── services/       entities: one page per microservice or repo project
├── infra/          stubs: pointers to infra/*.md (Pulumi project, AWS audit)
├── concepts/       cross-cutting topics (events, deploy, auth, …)
├── runbooks/       how-to guides
├── decisions/      design decisions (ADR-style)  — empty for now
├── archive/        retired content (functional-epics/, technical-epics/, …)
└── index.md        you are here

Read the kind: field on each page's frontmatter to know what shape to expect.

Architecture (concepts)

Cross-cutting concepts

Accounting model

Testing & quality

  • Cross-service BDD scenario catalog (EN/FR) — every @adb/e2e-api Gherkin scenario in English + French, generated from the .feature @i18n: tags and the per-service scenarios/<svc>.json seeds (node tools/scenario-catalog.mjs).
  • Test coverage — unit gates and capability coverage — the two things called coverage: the 85% vitest gate (red by design until the fan-out lands) and the 248-capability index measured against the live staging app, 63% covered, with the 21 confirmed defects it found and the 5 findings withdrawn on re-measurement.
  • Staging end-to-end suite (Playwright) — 642 tests driving the deployed Angular app, how to run them, the two opposed kinds of spec (specs/** records a defect and is green, specs-desired/** specifies the fix and is red), and what keeps a run from writing on someone else's data.
  • Coverage report — apps, packages, services — generated (pnpm report:coverage): per-member line/branch coverage over the three product directories, the workspace total as a sum rather than an average, the members whose run failed, and the ones that produced no figure at all.
  • End-to-end suite report — staging — generated (pnpm report:e2e): the suite's inventory by area, the capability coverage by verdict, and the confirmed defects by severity. Does not run the suite.

Services (entities)

Backend (Java / Spring WebFlux):

Frontend:

Infrastructure & tooling:

External / non-monorepo:

Infrastructure (stubs to infra/*.md)

Runbooks

  • Onboarding a new engineer — the real 12-week learning path: local stack, one request traced end to end, the JVM→Cloudflare port, tests, front end, auth, infra, and working with agents. Start here.
  • Provision a new environment — using infra/scripts/new-env.sh.
  • Deploy a PR preview — /deploy and /destroy PR comments.
  • Run the local stack — make up from infra/.
  • Local Atlas Search ($search) — make up-search + make search-indexes for local $search.
  • Re-point the staging files bucket — tools/scripts/files-bucket-migrate.mjs fixes the 502s on GET /files/:id in staging.
  • Migrate ticket type INCIDENT to DAMAGE — tools/scripts/migrate-incident-damage.mjs, staging first then production at the 0.69 roll-out; dry-run, guarded $set, rollback log.
  • Migrate Cloudflare ledger lines to the JVM account shape — tools/scripts/migrate-entry-account-shape.mjs: the account of lines written flat / id-less → AccountingEntryAccountDetails through the posting seam's resolver; dry-run, guarded $set, rollback log.
  • Migrate Worker-stored allocation keys to the JVM entity shape — tools/scripts/migrate-allocation-key-shape.mjs: legacy allocation-key request bodies → AllocationKeyEntity through lot 62's write mapper; dry-run, guarded replaceOne, rollback log.
  • Merge the accounting sequence twin counters at the production cutover — services/accounting/scripts/migrate-accounting-sequence-org-spelling.mjs, run once at the cutover (JVM accounting writes quiesced): renames organizationId counters, merges twins keeping MAX (FEC #3 and #9), creates the two unique indexes; race-safe apply (conditioned writes, $max, re-plan) and EJSON backup since 2026-10-10; rehearsed on staging 2026-10-06.
  • Data migrations (pnpm migrate) — the tracked MongoDB migrations of packages/data/migrations (umzug, adb-system._migrations, checksum, lock, dry-run unless --apply); assert is the pre-deploy gate pnpm infra:setup runs. 0001–0006 applied on staging. Production mode since 2026-10-10: PROD_MONGO_URI, --i-know-this-is-prod + host typed back, cutover-only behind --cutover, preflights, --apply --plan <hash>.

Reference

Archive

The archive/ tree holds content that was true at some point but isn't actively maintained: functional-epics, technical-epics, productBoard, implicit. Anything in archive/ defaults to status: stale.

Conventions and meta