Add architecture documentation explaining the off-chain mirror and on-chain settlement relationship

[mikewheeleer]

Document the architecture and off-chain/on-chain settlement model

Description

Comments scattered through src/index.ts reference a relationship to an on-chain Escrow contract ("the same shape the on-chain Escrow contract persists", "off-chain mirror that the settlement job will drain", "mirrors compute_billing on the on-chain side"), but no document explains the overall architecture. Contributors cannot see the big picture of how this backend, the settlement job, and the contract fit together. This issue captures it.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add docs/architecture.md describing the data model (the ${agent}::${serviceId} accumulator, services, events), request lifecycle through the middleware chain, and the intended off-chain → on-chain settlement flow.
• Include a sequence diagram for record-usage → quote → settle and a note on where durability and the settlement job will plug in.
• Reference the relevant handlers/functions by name (recordEvent, usageKey, POST /api/v1/settle).
• Keep it accurate to the current in-memory implementation; mark planned pieces explicitly.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/docs-26-architecture
• Implement changes
  • Write code in: no production change; documentation only.
  • Write comprehensive tests in: none required.
  • Add documentation: add docs/architecture.md and link it from README.md.
  • Use a Mermaid sequence diagram for the settlement flow.
  • Validate security assumptions: document the current trust model honestly (open API until auth lands).
• Test and commit

Test and commit

• Run npm run build and npm test to confirm nothing breaks.
• Verify every referenced symbol/route exists in src/index.ts.
• Include a rendered preview note in the PR description.

Example commit message

docs: add architecture overview and settlement-flow diagram

Guidelines

• Minimum 95 percent test coverage for impacted modules (where applicable).
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.