Document accrual semantics, webhook delivery lifecycle, and the settlement flow against actual code

[greatest0fallt1me]

Description

docs/ARCHITECTURE.md describes a "Settlement Service" and a settlement data flow, but no such service exists in src/services/ (only transactionService.ts, accrualService.ts, eventIngestionService.ts, webhookDeliveryService.ts, and auditService.ts), and the accrual formula plus the outbound webhook delivery lifecycle are documented only as inline code comments. This leaves contributors without an authoritative description of how accrual, webhook delivery, and settlement actually behave today. This issue adds accurate, code-grounded documentation for these three areas.

Requirements and context

• Document the accrual formula exactly as implemented in src/services/accrualService.ts: accrued = ratePerSecond * max(0, min(now, endTime) - lastSettledAt), the non-active short-circuit to 0, and the 9-decimal toFixed(9) precision (tied to the decimal(20, 9) columns in src/db/schema.ts).
• Document the outbound webhook delivery lifecycle using src/services/webhookDeliveryService.ts and the webhook_deliveries table (pending/success/failed status, attempts, nextAttemptAt backoff, lastHttpStatus/lastError).
• Document the indexer ingestion semantics from src/routes/webhooks/indexer.ts: 200 for first-time events, 202 for duplicates, and the 401/400/500 failure mapping.
• Reconcile docs/ARCHITECTURE.md with reality: clearly mark the Settlement Service as planned/not-yet-implemented (or link to the settlement issue), so the diagram is not mistaken for current behavior.
• Non-functional: documentation only; no source changes; all file paths and symbol names cited must match the repo.

Acceptance criteria

• Accrual semantics (formula, non-active behavior, precision) are documented and match accrualService.ts.
• The webhook delivery lifecycle and retry/backoff fields are documented against webhook_deliveries.
• Indexer ingestion status codes (200/202/401/400/500) are documented against the route handler.
• docs/ARCHITECTURE.md no longer implies a Settlement Service exists in code when it does not.
• All cited file paths and symbols are accurate.
• npm run build still passes (no code touched).

Suggested execution

1. Fork the repo and create a branch — git checkout -b docs/settlement-accrual-webhook-semantics.
2. Implement changes — update docs/ARCHITECTURE.md and add/extend a docs page (e.g. docs/accrual-and-settlement.md) covering the three areas; cross-link from README.md.
3. Write/extend tests — this repo uses Jest + Supertest. No new tests are required for docs-only changes; verify nothing breaks by running the suite.
4. Test and commit —

npm run lint -- --max-warnings 0
npm run build
npm test

Example commit message

docs: document accrual, webhook delivery, and settlement semantics

Guidelines

No coverage change expected (documentation only). Ensure every code reference is verifiable against the current tree; keep diagrams consistent with implemented behavior. Timeframe: 96 hours.

[silentgeckoaudit3801]

I can take this one. I will keep it documentation-only: reconcile docs/ARCHITECTURE.md with the current services, add a code-grounded accrual/webhook/settlement semantics page citing the exact files and symbols, and cross-link it from README. I will wait for assignment/confirmation before opening a PR.