Split the monolithic src/index.ts into routers, middleware, and store modules

[mikewheeleer]

Refactor the monolithic index.ts into modular routers and middleware

Description

The entire backend — every route, middleware, in-memory store, and the error handler — lives in a single ~1145-line src/index.ts. This makes the file hard to navigate, review, and test in isolation, and it is the root cause of the low test coverage elsewhere in this campaign. This issue splits it into cohesive modules without changing behaviour.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Extract feature routers into src/routes/ (e.g. usage.ts, services.ts, billing.ts, apiKeys.ts, webhooks.ts, admin.ts, events.ts, meta.ts).
• Extract cross-cutting middleware (CORS, security headers, request-id, rate limit, pause guard, timer) into src/middleware/.
• Extract the in-memory stores and recordEvent/usageKey helpers into src/store/ and src/events.ts.
• Keep src/index.ts as a thin composition root that still exports app so src/health.test.ts keeps passing unchanged; preserve every route path, status code, and response shape.

Suggested execution

• Fork the repo and create a branch
• git checkout -b refactor/api-27-modularize-index
• Implement changes
  • Write code in: new files under src/routes/, src/middleware/, src/store/, and a slimmed src/index.ts.
  • Write comprehensive tests in: keep src/health.test.ts green; add a src/routes/usage.test.ts demonstrating a router can be tested in isolation.
  • Add documentation: update the "Project structure" section of README.md.
  • Add TSDoc on each new module's public surface.
  • Validate security assumptions: middleware ordering (rate limit, pause guard, auth) is preserved exactly.
• Test and commit

Test and commit

• Run npm run build, npm test, and npm run lint.
• Confirm the full existing test suite passes unchanged and the OpenAPI doc still lists the same paths.
• Include the full npm test output in the PR description.

Example commit message

refactor: split index.ts into modular routers, middleware, and stores

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• 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.