@laitszkin/apollo-toolkit 3.9.7 → 3.11.0

package/init-project-html/sample-demo/resources/project-architecture/assets/architecture.css

@@ -0,0 +1,140 @@
+/* architecture.css — styling for the declarative atlas. The CLI copies
+ * this file into <outDir>/assets/. Style hooks (class names) are owned
+ * by render.js so agents never need to touch HTML by hand. */
+
+:root {
+  color-scheme: light dark;
+  --bg: #0f172a;
+  --panel: #111827;
+  --panel-soft: #1f2937;
+  --text: #e5e7eb;
+  --muted: #9ca3af;
+  --border: #334155;
+  --accent: #38bdf8;
+  --kind-ui: #38bdf8;
+  --kind-api: #818cf8;
+  --kind-service: #34d399;
+  --kind-db: #fbbf24;
+  --kind-pure-fn: #cbd5e1;
+  --kind-queue: #a78bfa;
+  --kind-external: #fb7185;
+  --edge-call: #60a5fa;
+  --edge-return: #94a3b8;
+  --edge-data-row: #fbbf24;
+  --edge-failure: #fb7185;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: var(--bg); color: var(--text); font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+h1, h2 { margin: 0 0 12px; font-weight: 600; letter-spacing: -0.01em; }
+h1 { font-size: 28px; }
+h2 { font-size: 18px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; font-size: 13px; }
+
+p { line-height: 1.55; color: var(--text); }
+
+/* ---- atlas (macro) ---- */
+.atlas-header { padding: 28px 40px 16px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.atlas-summary { color: var(--muted); max-width: 80ch; margin: 8px 0 0; }
+
+.atlas-main { display: grid; grid-template-columns: minmax(0, 3fr) minmax(280px, 1fr); gap: 24px; padding: 24px 40px 48px; }
+
+.atlas-canvas { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; position: relative; }
+.atlas-canvas__toolbar { position: absolute; top: 16px; right: 16px; display: flex; gap: 4px; z-index: 2; }
+.atlas-canvas__toolbar button { background: var(--panel-soft); color: var(--text); border: 1px solid var(--border); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.atlas-canvas__toolbar button:hover { border-color: var(--accent); color: var(--accent); }
+
+.atlas-canvas__viewport { width: 100%; max-height: 72vh; overflow: hidden; border-radius: 8px; background: #0b1220; }
+.atlas-canvas__viewport.is-grabbing { cursor: grabbing; }
+.atlas-canvas__viewport:not(.is-grabbing) { cursor: grab; }
+
+.atlas-svg { width: 100%; height: auto; max-height: 72vh; display: block; user-select: none; touch-action: none; }
+
+.atlas-legend { list-style: none; padding: 12px 4px 0; margin: 0; display: flex; gap: 18px; flex-wrap: wrap; font-size: 12px; color: var(--muted); }
+.atlas-legend li { display: inline-flex; align-items: center; gap: 6px; }
+.legend-swatch { display: inline-block; width: 18px; height: 4px; border-radius: 2px; }
+.legend-swatch--call { background: var(--edge-call); }
+.legend-swatch--return { background: var(--edge-return); }
+.legend-swatch--data-row { background: var(--edge-data-row); }
+.legend-swatch--failure { background: var(--edge-failure); }
+
+.atlas-index { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; max-height: 80vh; overflow: auto; }
+
+.atlas-submodule-index { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 10px; }
+.atlas-submodule-index__item a { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: 4px 8px; padding: 8px 10px; background: var(--panel-soft); border: 1px solid var(--border); border-radius: 8px; color: inherit; }
+.atlas-submodule-index__item a:hover { border-color: var(--accent); }
+.atlas-submodule-index__feature { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; grid-column: 1 / 3; }
+.atlas-submodule-index__sub { font-weight: 600; }
+.atlas-submodule-index__kind { font-size: 11px; padding: 1px 8px; border-radius: 999px; background: var(--panel); border: 1px solid var(--border); color: var(--muted); }
+.atlas-submodule-index__role { margin: 4px 10px 0; font-size: 12px; color: var(--muted); }
+
+/* ---- SVG macro ---- */
+.m-cluster__bg { fill: rgba(15, 23, 42, 0.55); stroke: var(--border); stroke-width: 1; }
+.m-cluster__title { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
+.m-node rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease; }
+.m-node:hover rect { stroke: var(--accent); }
+.m-node__title { font-size: 13px; font-weight: 600; fill: var(--text); }
+.m-node__kind { font-size: 11px; fill: var(--muted); }
+.m-node__role { font-size: 11px; fill: var(--muted); }
+
+.m-node--ui rect { stroke: var(--kind-ui); }
+.m-node--api rect { stroke: var(--kind-api); }
+.m-node--service rect { stroke: var(--kind-service); }
+.m-node--db rect { stroke: var(--kind-db); }
+.m-node--pure-fn rect { stroke: var(--kind-pure-fn); }
+.m-node--queue rect { stroke: var(--kind-queue); }
+.m-node--external rect { stroke: var(--kind-external); }
+
+.m-edge path { stroke-width: 1.6; }
+.m-edge--call path { stroke: var(--edge-call); }
+.m-edge--return path { stroke: var(--edge-return); stroke-dasharray: 6 4; }
+.m-edge--data-row path { stroke: var(--edge-data-row); }
+.m-edge--failure path { stroke: var(--edge-failure); }
+
+.m-arrow path { fill: currentColor; }
+.m-arrow--call { color: var(--edge-call); }
+.m-arrow--return { color: var(--edge-return); }
+.m-arrow--data-row { color: var(--edge-data-row); }
+.m-arrow--failure { color: var(--edge-failure); }
+
+.m-edge__label { fill: var(--muted); font-size: 11px; }
+
+/* ---- feature page ---- */
+.feature-header, .submodule-header { padding: 24px 40px 12px; border-bottom: 1px solid var(--border); background: var(--panel); }
+.feature-breadcrumb, .submodule-breadcrumb { font-size: 13px; color: var(--muted); margin-bottom: 8px; }
+.feature-depends { font-size: 13px; color: var(--muted); margin: 8px 0 0; }
+.feature-main, .submodule-main { padding: 24px 40px 48px; display: flex; flex-direction: column; gap: 32px; }
+.feature-story p { max-width: 80ch; }
+
+.submodule-nav { list-style: none; padding: 0; margin: 0; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+.submodule-card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 12px 14px; }
+.submodule-card__link { display: flex; align-items: center; justify-content: space-between; color: inherit; font-weight: 600; }
+.submodule-card__kind { font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); }
+.submodule-card__role { margin: 8px 0 0; font-size: 13px; color: var(--muted); }
+
+.feature-edges__list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 8px; }
+.feature-edges__item { display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 2fr); gap: 8px; padding: 8px 12px; background: var(--panel); border: 1px solid var(--border); border-radius: 8px; font-size: 13px; }
+.feature-edges__kind { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; align-self: center; }
+.feature-edges__item--call { border-left: 4px solid var(--edge-call); }
+.feature-edges__item--return { border-left: 4px solid var(--edge-return); }
+.feature-edges__item--data-row { border-left: 4px solid var(--edge-data-row); }
+.feature-edges__item--failure { border-left: 4px solid var(--edge-failure); }
+
+/* ---- submodule page ---- */
+.submodule-kind { display: inline-block; font-size: 12px; padding: 2px 10px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); margin-left: 8px; vertical-align: middle; text-transform: uppercase; letter-spacing: 0.06em; }
+.submodule-role { color: var(--muted); margin: 8px 0 0; max-width: 80ch; }
+
+.sub-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.sub-table th, .sub-table td { padding: 8px 12px; border-bottom: 1px solid var(--border); text-align: left; vertical-align: top; }
+.sub-table th { font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; background: var(--panel); }
+
+.sub-section__empty { color: var(--muted); font-style: italic; font-size: 13px; }
+
+.sub-dataflow__svg { width: 100%; max-width: 480px; }
+.sub-dataflow__step rect { fill: var(--panel); stroke: var(--border); }
+.sub-dataflow__step text { fill: var(--text); font-size: 13px; }
+.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.4; }
+.sub-dataflow__empty { color: var(--muted); font-style: italic; }

package/init-project-html/sample-demo/resources/project-architecture/assets/viewer.client.js

@@ -0,0 +1,93 @@
+/* viewer.client.js — pan/zoom for the macro atlas SVG. No deps; wires
+ * onto any element marked [data-pan-zoom-viewport] containing one
+ * [data-atlas-svg] SVG. Mouse wheel zooms around the cursor; drag pans;
+ * toolbar buttons handle +/-/Fit; keyboard arrows pan. */
+
+(function () {
+  'use strict';
+
+  const viewport = document.querySelector('[data-pan-zoom-viewport]');
+  if (!viewport) return;
+  const svg = viewport.querySelector('[data-atlas-svg]');
+  if (!svg) return;
+
+  const initial = svg.getAttribute('viewBox');
+  if (!initial) return;
+  const [ix, iy, iw, ih] = initial.split(/\s+/).map(Number);
+  const state = { x: ix, y: iy, w: iw, h: ih };
+
+  function apply() {
+    svg.setAttribute('viewBox', `${state.x} ${state.y} ${state.w} ${state.h}`);
+  }
+
+  function zoom(factor, cx, cy) {
+    const newW = Math.max(40, Math.min(state.w * factor, iw * 8));
+    const newH = newW * (state.h / state.w);
+    if (cx == null) { cx = state.x + state.w / 2; cy = state.y + state.h / 2; }
+    state.x = cx - (cx - state.x) * (newW / state.w);
+    state.y = cy - (cy - state.y) * (newH / state.h);
+    state.w = newW;
+    state.h = newH;
+    apply();
+  }
+
+  function clientToSvg(evt) {
+    const rect = svg.getBoundingClientRect();
+    const xRatio = (evt.clientX - rect.left) / rect.width;
+    const yRatio = (evt.clientY - rect.top) / rect.height;
+    return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
+  }
+
+  viewport.addEventListener('wheel', function (evt) {
+    if (!evt.ctrlKey && !evt.metaKey && Math.abs(evt.deltaY) < 4 && Math.abs(evt.deltaX) < 4) return;
+    evt.preventDefault();
+    const factor = evt.deltaY > 0 ? 1.1 : 1 / 1.1;
+    const pt = clientToSvg(evt);
+    zoom(factor, pt.x, pt.y);
+  }, { passive: false });
+
+  let dragging = null;
+  viewport.addEventListener('pointerdown', function (evt) {
+    if (evt.button !== 0) return;
+    dragging = { x: evt.clientX, y: evt.clientY };
+    viewport.classList.add('is-grabbing');
+    viewport.setPointerCapture(evt.pointerId);
+  });
+  viewport.addEventListener('pointermove', function (evt) {
+    if (!dragging) return;
+    const rect = svg.getBoundingClientRect();
+    const dx = ((evt.clientX - dragging.x) / rect.width) * state.w;
+    const dy = ((evt.clientY - dragging.y) / rect.height) * state.h;
+    state.x -= dx;
+    state.y -= dy;
+    dragging = { x: evt.clientX, y: evt.clientY };
+    apply();
+  });
+  function endDrag(evt) {
+    if (!dragging) return;
+    dragging = null;
+    viewport.classList.remove('is-grabbing');
+    try { viewport.releasePointerCapture(evt.pointerId); } catch (e) { /* ignore */ }
+  }
+  viewport.addEventListener('pointerup', endDrag);
+  viewport.addEventListener('pointercancel', endDrag);
+  viewport.addEventListener('pointerleave', endDrag);
+
+  document.addEventListener('keydown', function (evt) {
+    if (evt.target && (evt.target.tagName === 'INPUT' || evt.target.tagName === 'TEXTAREA')) return;
+    const step = state.w * 0.08;
+    if (evt.key === 'ArrowLeft') { state.x -= step; apply(); }
+    else if (evt.key === 'ArrowRight') { state.x += step; apply(); }
+    else if (evt.key === 'ArrowUp') { state.y -= step; apply(); }
+    else if (evt.key === 'ArrowDown') { state.y += step; apply(); }
+    else if (evt.key === '+' || evt.key === '=') { zoom(1 / 1.2); }
+    else if (evt.key === '-' || evt.key === '_') { zoom(1.2); }
+    else if (evt.key === '0') { state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply(); }
+  });
+
+  document.querySelectorAll('[data-pan-zoom="zoom-in"]').forEach((btn) => btn.addEventListener('click', () => zoom(1 / 1.2)));
+  document.querySelectorAll('[data-pan-zoom="zoom-out"]').forEach((btn) => btn.addEventListener('click', () => zoom(1.2)));
+  document.querySelectorAll('[data-pan-zoom="fit"]').forEach((btn) => btn.addEventListener('click', () => {
+    state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply();
+  }));
+})();

package/init-project-html/sample-demo/resources/project-architecture/atlas/atlas.index.yaml

@@ -0,0 +1,34 @@
+meta:
+  title: Acme App — sample atlas
+  summary: >-
+    Two end-to-end feature modules — minting invite codes and consuming them during account
+    registration — produced by `apltk architecture` from a declarative YAML source. The macro
+    diagram surfaces both feature clusters and every sub-module they own, plus the cross-feature
+    data-row that carries an `invite_codes` row between them.
+actors:
+  - id: visitor
+    label: Visitor (unregistered)
+  - id: member
+    label: Authenticated member
+features:
+  - get-invite-codes
+  - invite-code-registration
+edges:
+  - id: cross-issuance-to-postgres-codes
+    from:
+      feature: get-invite-codes
+      submodule: invite-issuance-service
+    to:
+      feature: get-invite-codes
+      submodule: postgresql
+    kind: data-row
+    label: INSERT invite_codes
+  - id: cross-postgres-codes-to-registration
+    from:
+      feature: get-invite-codes
+      submodule: postgresql
+    to:
+      feature: invite-code-registration
+      submodule: registration-service
+    kind: data-row
+    label: read/consume invite_codes

package/init-project-html/sample-demo/resources/project-architecture/atlas/features/get-invite-codes.yaml

@@ -0,0 +1,159 @@
+slug: get-invite-codes
+title: Get invite codes
+story: >-
+  An authenticated member requests a new invite code that they can hand to an off-platform
+  visitor. The issuance service mints a fresh code, persists it in `invite_codes`, and returns
+  the code string to the UI. Issued rows then become the producer side of the
+  `invite-code-registration` flow.
+dependsOn: []
+submodules:
+  - slug: web-get-invite-ui
+    kind: ui
+    role: React page that lets a signed-in member request a new invite code.
+    functions:
+      - name: handleGenerate
+        in: MouseEvent
+        out: void
+        side: io
+        purpose: Calls POST /api/invites and renders the returned code.
+    variables:
+      - name: userId
+        type: string
+        scope: call
+        purpose: Identifies the member who will own the new invite row.
+      - name: code
+        type: string
+        scope: instance
+        purpose: Last issued code shown to the member.
+    dataflow:
+      - Read userId from auth context.
+      - POST /api/invites with userId.
+      - Render returned code or surface error.
+    errors:
+      - name: ErrUnauthenticated
+        when: Session is missing on the client.
+        means: Redirect to sign-in.
+      - name: ErrIssuanceFailed
+        when: API returns 500.
+        means: Show retry banner.
+  - slug: public-api
+    kind: api
+    role: HTTP boundary for `/api/invites` POST requests.
+    functions:
+      - name: postInvites
+        in: HttpRequest
+        out: HttpResponse
+        side: network
+        purpose: Validates the bearer token then delegates to invite-issuance-service.
+    variables:
+      - name: token
+        type: string
+        scope: call
+        purpose: Bearer token used to resolve the requesting member.
+    dataflow:
+      - Validate Authorization header.
+      - Resolve userId from token.
+      - Call invite-issuance-service.Issue.
+      - Serialize response.
+    errors:
+      - name: ErrUnauthorized
+        when: Token missing or invalid.
+        means: 401 response.
+  - slug: invite-issuance-service
+    kind: service
+    role: Domain service that mints and persists a single invite row per request.
+    functions:
+      - name: Issue
+        in: ctx, userId
+        out: InviteCode | error
+        side: tx
+        purpose: Generates a unique code and writes the matching invite_codes row.
+      - name: generateCode
+        in: rand
+        out: code
+        side: pure
+        purpose: Produces a 10-char alphanumeric token.
+    variables:
+      - name: code
+        type: string
+        scope: tx
+        purpose: Newly minted invite token recorded against the member.
+      - name: row
+        type: InviteCodeRow
+        scope: tx
+        purpose: Persisted invite_codes row carrying owner, code, expiry, and consumption state.
+    dataflow:
+      - Open transaction.
+      - Generate candidate code via generateCode.
+      - INSERT invite_codes row (retry on unique-violation).
+      - Commit and return code.
+    errors:
+      - name: ErrCollision
+        when: Unique constraint on code repeatedly violated.
+        means: Surface 503 after retry budget exhausted.
+  - slug: invite-code-generator
+    kind: pure-fn
+    role: Pure helper that turns random bytes into a printable invite code.
+    functions:
+      - name: encode
+        in: bytes[8]
+        out: code
+        side: pure
+        purpose: Base32 encoding without padding for human-readable codes.
+    variables: []
+    dataflow:
+      - Read 8 random bytes.
+      - Base32 encode without padding.
+    errors: []
+  - slug: postgresql
+    kind: db
+    role: Owns the `invite_codes` table (producer side of the cross-feature data row).
+    functions:
+      - name: INSERT_invite_codes
+        in: row
+        out: rowid
+        side: write
+        purpose: Persists the issued invite row.
+    variables:
+      - name: invite_codes.code
+        type: text
+        scope: persist
+        purpose: Unique business key consumed by the registration flow.
+      - name: invite_codes.consumed_at
+        type: timestamptz
+        scope: persist
+        purpose: Stays null until the registration flow consumes the code.
+    dataflow:
+      - Accept INSERT from invite-issuance-service.
+      - Enforce unique constraint on code.
+      - Return new rowid.
+    errors:
+      - name: ErrUniqueViolation
+        when: Two issuance attempts pick the same code.
+        means: Bubble up so issuance can retry.
+edges:
+  - id: e-ui-api
+    from: web-get-invite-ui
+    to: public-api
+    kind: call
+    label: POST /api/invites
+  - id: e-api-svc
+    from: public-api
+    to: invite-issuance-service
+    kind: call
+    label: Issue(ctx, userId)
+  - id: e-svc-gen
+    from: invite-issuance-service
+    to: invite-code-generator
+    kind: call
+    label: encode(rand)
+  - id: e-svc-db
+    from: invite-issuance-service
+    to: postgresql
+    kind: call
+    label: INSERT invite_codes
+  - id: e-db-svc-return
+    from: postgresql
+    to: invite-issuance-service
+    kind: return
+    label: rowid

package/init-project-html/sample-demo/resources/project-architecture/atlas/features/invite-code-registration.yaml

@@ -0,0 +1,160 @@
+slug: invite-code-registration
+title: Invite-code registration
+story: >-
+  A visitor holding an invite code submits email/password plus the code. The registration
+  service validates the code inside a single transaction; on success it creates a new user
+  and consumes the invite_codes row issued earlier by `get-invite-codes`.
+dependsOn:
+  - get-invite-codes
+submodules:
+  - slug: web-register-ui
+    kind: ui
+    role: React page that captures email, password, and invite code.
+    functions:
+      - name: handleSubmit
+        in: FormEvent
+        out: void
+        side: io
+        purpose: POSTs the registration payload and routes the response.
+    variables:
+      - name: email
+        type: string
+        scope: call
+        purpose: Identity for the new account; required.
+      - name: inviteCode
+        type: string
+        scope: call
+        purpose: Token from the off-platform invite hand-off.
+    dataflow:
+      - Collect form fields.
+      - POST /api/register with payload.
+      - On 2xx redirect to /welcome; otherwise surface field-level errors.
+    errors:
+      - name: ErrInvalidCode
+        when: API returns 422 with `invite_code` reason.
+        means: Highlight the invite-code field with the API message.
+  - slug: public-api
+    kind: api
+    role: HTTP boundary for `/api/register` POST requests.
+    functions:
+      - name: postRegister
+        in: HttpRequest
+        out: HttpResponse
+        side: network
+        purpose: Parses payload and delegates to registration-service.
+    variables:
+      - name: payload
+        type: RegisterDTO
+        scope: call
+        purpose: Inbound registration intent.
+    dataflow:
+      - Decode JSON body.
+      - Call registration-service.RegisterWithInvite.
+      - Serialize success or 422 / 5xx error.
+    errors:
+      - name: ErrMalformedPayload
+        when: JSON parse fails.
+        means: 400 response with `payload` reason.
+  - slug: registration-service
+    kind: service
+    role: Owns the registration transaction (consumer side of the invite_codes data row).
+    functions:
+      - name: RegisterWithInvite
+        in: ctx, RegisterInput
+        out: NewUserID | ErrInvalidCode | ErrEmailTaken
+        side: tx
+        purpose: Validates code, hashes password, inserts user, consumes invite.
+      - name: decideInviteValid
+        in: row, now
+        out: true | ErrInvalidCode
+        side: pure
+        purpose: Checks existence, expiry, consumption state.
+    variables:
+      - name: inviteRow
+        type: InviteCodeRow
+        scope: tx
+        purpose: Row read with SELECT FOR UPDATE; gates the rest of the flow.
+      - name: passwordHash
+        type: string
+        scope: tx
+        purpose: bcrypt/argon2 hash of the submitted password; plaintext is discarded.
+    dataflow:
+      - Open transaction.
+      - SELECT invite_codes FOR UPDATE WHERE code = ?
+      - decideInviteValid against current time.
+      - INSERT users row and UPDATE invite_codes.consumed_at.
+      - Commit and return NewUserID.
+    errors:
+      - name: ErrInvalidCode
+        when: Row missing, expired, or already consumed.
+        means: 422 response with `invite_code` reason.
+      - name: ErrEmailTaken
+        when: Unique violation on users.email.
+        means: 422 response with `email` reason.
+  - slug: postgresql
+    kind: db
+    role: Stores `users` rows and applies invite-code state transitions inside the registration tx.
+    functions:
+      - name: SELECT_invite_for_update
+        in: code
+        out: InviteCodeRow | nil
+        side: lock
+        purpose: Locks the invite row for the duration of the transaction.
+      - name: INSERT_users
+        in: userRow
+        out: userId
+        side: write
+        purpose: Persists the new account.
+      - name: UPDATE_invite_consumed
+        in: code, now
+        out: rows_affected
+        side: write
+        purpose: Marks the invite as consumed.
+    variables:
+      - name: users.email
+        type: text
+        scope: persist
+        purpose: Unique account identity.
+      - name: invite_codes.consumed_at
+        type: timestamptz
+        scope: persist
+        purpose: Timestamp set the moment the invite row is consumed.
+    dataflow:
+      - Apply row lock on invite_codes.
+      - Validate uniqueness of users.email.
+      - Write users row and update invite_codes.consumed_at.
+    errors:
+      - name: ErrUniqueEmail
+        when: users.email unique constraint violated.
+        means: Bubble up so service can return ErrEmailTaken.
+edges:
+  - id: e-ui-api
+    from: web-register-ui
+    to: public-api
+    kind: call
+    label: POST /api/register
+  - id: e-api-svc
+    from: public-api
+    to: registration-service
+    kind: call
+    label: RegisterWithInvite(ctx, RegisterInput)
+  - id: e-svc-db-select
+    from: registration-service
+    to: postgresql
+    kind: call
+    label: SELECT invite_codes FOR UPDATE
+  - id: e-svc-db-insert
+    from: registration-service
+    to: postgresql
+    kind: call
+    label: INSERT users
+  - id: e-svc-db-update
+    from: registration-service
+    to: postgresql
+    kind: call
+    label: UPDATE invite_codes.consumed_at
+  - id: e-db-svc-return
+    from: postgresql
+    to: registration-service
+    kind: return
+    label: row | rows_affected

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/index.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en" data-atlas-page="feature">
+<head>
+  <meta charset="utf-8">
+  <title>Get invite codes</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="../../assets/architecture.css">
+</head>
+<body>
+  <header class="feature-header">
+    <nav class="feature-breadcrumb"><a href="../../index.html">← Atlas</a></nav>
+    <h1>Get invite codes</h1>
+    
+  </header>
+  <main class="feature-main">
+    <section class="feature-story"><p>An authenticated member requests a new invite code that they can hand to an off-platform visitor. The issuance service mints a fresh code, persists it in `invite_codes`, and returns the code string to the UI. Issued rows then become the producer side of the `invite-code-registration` flow.</p></section>
+    <section class="feature-submodules" aria-label="Submodules">
+      <h2>Submodules</h2>
+      <ul class="submodule-nav">
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="web-get-invite-ui.html">
+          <span class="submodule-card__name">web-get-invite-ui</span>
+          <span class="submodule-card__kind submodule-card__kind--ui">UI</span>
+        </a>
+        <p class="submodule-card__role">React page that lets a signed-in member request a new invite code.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="public-api.html">
+          <span class="submodule-card__name">public-api</span>
+          <span class="submodule-card__kind submodule-card__kind--api">API</span>
+        </a>
+        <p class="submodule-card__role">HTTP boundary for `/api/invites` POST requests.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="invite-issuance-service.html">
+          <span class="submodule-card__name">invite-issuance-service</span>
+          <span class="submodule-card__kind submodule-card__kind--service">Service</span>
+        </a>
+        <p class="submodule-card__role">Domain service that mints and persists a single invite row per request.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="invite-code-generator.html">
+          <span class="submodule-card__name">invite-code-generator</span>
+          <span class="submodule-card__kind submodule-card__kind--pure-fn">Pure fn</span>
+        </a>
+        <p class="submodule-card__role">Pure helper that turns random bytes into a printable invite code.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="postgresql.html">
+          <span class="submodule-card__name">postgresql</span>
+          <span class="submodule-card__kind submodule-card__kind--db">DB</span>
+        </a>
+        <p class="submodule-card__role">Owns the `invite_codes` table (producer side of the cross-feature data row).</p>
+      </li>
+      </ul>
+    </section>
+    <section class="feature-edges" aria-label="Intra-feature edges">
+      <h2>Intra-feature edges</h2>
+      <ul class="feature-edges__list">
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">web-get-invite-ui → public-api</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">POST /api/invites</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">public-api → invite-issuance-service</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">Issue(ctx, userId)</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">invite-issuance-service → invite-code-generator</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">encode(rand)</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">invite-issuance-service → postgresql</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">INSERT invite_codes</span></li>
+        <li class="feature-edges__item feature-edges__item--return"><span class="feature-edges__endpoints">postgresql → invite-issuance-service</span><span class="feature-edges__kind">return</span><span class="feature-edges__label">rowid</span></li>
+      </ul>
+    </section>
+  </main>
+</body>
+</html>