refactor(platform): centralized config, OpenAPI validation, domain modules, error code registry

[CeceOs92]

This PR implements 4 foundational refactors for AgenticPay: centralized configuration with dynamic reload, OpenAPI-driven validation, domain-driven frontend modules, and unified error code registry.

What's Changed

Centralized Configuration Service - #481

• New backend/src/services/config/ with hierarchical resolution: defaults < env < database < runtime override
• config-store.ts abstracts storage via Prisma + Redis pub/sub for change notifications
• Dynamic reload: subscribed services receive config.updated event, refresh without restart
• Admin API: GET/PATCH /api/admin/config for read/update
• Audit log: ConfigAuditLog model tracks who changed what + when
• Config export/import endpoints for env migration
• Frontend: /admin/configuration UI with typed forms, validation, live preview
• Migration: moved feature flags, fee schedules, rate limits from env to AppConfiguration table
• Edge cases: validates values via schema, rejects partial invalid updates, handles concurrent mods with optimistic locking
• Events: config.changed published to Redis for downstream services

OpenAPI-Based Validation - #482

• New packages/api-spec/ with OpenAPI 3.1 definitions as single source of truth
• Codegen: OpenAPI → Zod schemas via openapi-zod-client for request validation
• Middleware backend/src/middleware/openapi-validator.ts: auto-validates all requests, serializes responses
• Swagger UI exposed at /api-docs using Scalar
• Conformance tests: validateResponseAgainstOpenAPI helper catches violations in CI
• Supports oneOf, anyOf, allOf, file uploads, binary responses
• Deprecation: @deprecated in OpenAPI adds Sunset header
• Removed ad-hoc Zod schemas from route handlers; all endpoints now spec-driven

Frontend Domain-Driven Modules - #483

• Reorganized frontend/src/domains/ into: payments, merchants, wallets, analytics, settings, developers
• Each domain: components/, hooks/, api/, types/, pages/ colocated
• Shared code moved to frontend/src/shared/ and frontend/src/ui/ for design system
• Barrel exports per domain + TS path aliases: @payments/hooks/usePaymentList
• ESLint plugin enforces domain boundaries; prevents cross-domain imports except via public API
• Codemod migrated all existing imports; zero circular dependencies
• Migration guide added to CONTRIBUTING.md
• Cross-domain state handled via shared/stores/ and global providers in app/providers.tsx

Unified Error Code Registry - #484

• Error format: ERR_<DOMAIN>_<TYPE> e.g. ERR_PAYMENT_INSUFFICIENT_FUNDS
• New packages/error-codes/ registry with description, HTTP status, resolution hints
• Standardized response: { error: { code, message, details, requestId } }
• backend/src/middleware/error-handler.ts maps all exceptions to standard format
• GET /api/errors returns full registry for discoverability
• SDK: typed error classes generated from registry in packages/sdk/src/errors/
• OpenAPI: each endpoint documents possible error codes in responses
• Categories: auth, validation, payment, blockchain, rate_limit, internal
• Deprecation: error codes marked deprecated with sunset timeline in registry
• Prevents sensitive leakage: details sanitized, stack traces only in dev

Testing Done

• Config: update via admin UI → Redis event → service reloads without restart; audit log created; invalid value rejected
• OpenAPI: POST /payments with missing field → 400 with Zod error; response schema violation fails CI
• Domains: pnpm lint → no boundary violations; codemod migrated 214 files; app builds/runs
• Errors: throw PaymentError.InsufficientFunds → response matches standard format; SDK throws typed error
• GET /api/errors returns registry; /api-docs renders all endpoints + error codes
• pnpm test → 64 new tests pass across backend/frontend
• pnpm lint && pnpm typecheck → clean

Notes

Breaking change: all error responses now standardized; SDK users must update catch blocks. Config migration script provided. OpenAPI spec is now required for new endpoints. Domain restructure improves codebase navigation and reduces coupling.

Closes #481
Closes #482
Closes #483
Closes #484

[vercel]

@CeceOs92 is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@CeceOs92 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits