Skip to content

API Route Documentation TODO (Router-Driven)

Purpose

This checklist is the source of truth for making backend API documentation complete and consistent with live route wiring.

Source of Truth

  • Router registration: app/api/v1/router.py
  • Endpoint modules: app/api/v1/endpoints/*.py
  • Current docs index: docs/README.md

Important Routing Notes

  • roles.py and policy.py attach routes to user_router (shared router object), so those endpoints are effectively under /api/v1/user/* even though they are imported as separate modules.
  • totp.py defines APIRouter(prefix="/totp") and is included with /2fa, making effective paths /api/v1/2fa/totp/*.
  • mobile_register.py, card.py, and socket.py are included with empty prefixes, so their paths are rooted directly under /api/v1/*.
  • faq.py currently defines routes but is not included in app/api/v1/router.py.

Coverage Matrix (By Included Router)

Effective Route Group Endpoint Module Approx. Route Count Primary Doc Target Current Status Gap Summary
/api/v1/auth/* auth.py 42 AUTHENTICATION.md, AUTHENTICATION_ENHANCED.md Verified Endpoint inventory reconciled to live route decorators in auth.py on 2026-06-28.
/api/v1/user/* users.py + roles.py + policy.py 36 USER_ROLE_MANAGEMENT.md, POLICY_MANAGEMENT.md Verified Endpoint inventory reconciled to live route decorators in users/roles/policy routers on 2026-06-28.
/api/v1/core/* core.py 17 CORE_INTEGRATION.md Verified Endpoint inventory reconciled to live route decorators in core.py on 2026-06-28.
/api/v1/customer/* customer.py 24 CUSTOMER_MANAGEMENT.md Verified Endpoint inventory reconciled to live route decorators in customer.py on 2026-06-28.
/api/v1/document/* document.py 19 DOCUMENT_SERVICE.md, SUPPORTING_MODULES.md Verified Endpoint inventory reconciled to live route decorators in document.py on 2026-06-28.
/api/v1/transaction/* transaction.py 45 TRANSACTION_PROCESSING.md Verified Endpoint inventory reconciled to live route decorators in transaction.py on 2026-06-28.
/api/v1/wallet/* wallet.py 72 WALLET_PAYMENT_SERVICES.md (+ wallet companion docs) Verified Endpoint inventory reconciled to live route decorators in wallet.py on 2026-06-28.
/api/v1/integration/* integration.py 14 CORE_INTEGRATION.md Verified Endpoint inventory reconciled to live route decorators in integration.py on 2026-06-28.
/api/v1/app/* app.py 5 APP_EXPERIENCE.md Verified Endpoint inventory reconciled to live route decorators in app.py on 2026-06-28.
/api/v1/ussd/* ussd.py 4 NOTIFICATIONS_USSD.md Verified Endpoint inventory reconciled to live route decorators in ussd.py on 2026-06-28.
/api/v1/notify/* notify.py 11 NOTIFICATIONS_USSD.md, NOTIFY_TESTS_README.md Verified Endpoint inventory reconciled to live route decorators in notify.py on 2026-06-28.
/api/v1/agent/* agent.py 47 AGENT_MANAGEMENT.md Verified Endpoint inventory reconciled to live route decorators in agent.py on 2026-06-28.
/api/v1/ai-agent/* ai_agent.py 3 AI_AGENT.md, ai_agent_module.md Verified Endpoint inventory reconciled to live route decorators in ai_agent.py on 2026-06-28.
/api/v1/report/* report.py 3 REPORTING_ANALYTICS.md Verified Endpoint inventory reconciled to live route decorators in report.py on 2026-06-28.
/api/v1/aml/* aml.py 20 AML.md Verified Endpoint inventory reconciled to live route decorators in aml.py on 2026-06-28.
/api/v1/campaign/* campaign.py 28 CAMPAIGN_INVENTORY.md Verified Endpoint inventory reconciled to live route decorators in campaign.py on 2026-06-28.
/api/v1/inventory/* inventory.py 13 CAMPAIGN_INVENTORY.md Verified Endpoint inventory reconciled to live route decorators in inventory.py on 2026-06-28.
/api/v1/loan/* loan.py 87 LOAN_MANAGEMENT.md (+ loan scoring docs) Verified Endpoint inventory reconciled to live route decorators in loan.py on 2026-06-28.
/api/v1/support/* support.py 12 SUPPORT_OPERATIONS.md Verified Endpoint inventory reconciled to live route decorators in support.py on 2026-06-28.
/api/v1/2fa/totp/* totp.py 9 AUTHENTICATION.md, SUPPORTING_MODULES.md Verified Endpoint inventory reconciled to live route decorators in totp.py on 2026-06-28.
/api/v1/admin/config/* config.py 8 CORE_INTEGRATION.md or dedicated config doc Verified Endpoint inventory reconciled to live route decorators in config.py on 2026-06-28.
/api/v1/reconciliation/* reconciliation.py 12 RECONCILIATION.md Verified Endpoint inventory reconciled to live route decorators in reconciliation.py on 2026-06-28.
/api/v1/permissions permissions.py 2 PERMISSIONS.md, USER_ROLE_MANAGEMENT.md Verified Endpoint inventory reconciled to live route decorators in permissions.py on 2026-06-28.
/api/v1/mobile/register/* mobile_register.py 12 MOBILE_REGISTRATION.md, DIDIT docs Verified Endpoint inventory reconciled to live route decorators in mobile_register.py on 2026-06-28.
/api/v1/card/* card.py 5 CARD_MANAGEMENT.md Verified Endpoint inventory reconciled to live route decorators in card.py on 2026-06-28.
/api/v1/ws* socket.py (websocket) 2 websocket routes SOCKET_REALTIME.md Verified WebSocket routes reconciled to live decorators in socket.py on 2026-06-28.

Unwired or Ambiguous Modules

  • [ ] faq.py: has route handlers but not included in app/api/v1/router.py.
  • Action: either include it intentionally or mark it as deprecated/internal in docs.
  • [ ] ai.py: appears inactive/commented.
  • Action: document as deprecated/internal if intentionally not public.
  • [ ] roles_router and policy_router are imported in app/api/v1/router.py but not directly included.
  • Action: document this implementation detail explicitly in routing docs to avoid confusion.

Airtight Documentation Definition (Acceptance Criteria)

For each included route group above, documentation is considered complete only when all of the following are present: - [ ] Endpoint inventory table: method, path, purpose, auth/permission, request schema, response schema. - [ ] Business workflow mapping: where endpoints belong in real user/system journeys. - [ ] Validation and error matrix: expected 4xx/5xx with representative payloads. - [ ] Security constraints: token type, permission string, superuser/admin requirements. - [ ] Cross-module dependencies: external services, downstream calls, async jobs/events. - [ ] Versioning/deprecation notes: active, legacy, or transitional routes clearly marked.

Priority Execution Plan

  1. Critical breadth first: Loan, Wallet, Transaction, Agent, Auth.
  2. Security and controls: User/Role/Policy, TOTP, Permissions, Config.
  3. Integration and channels: Integration, Notify, USSD, Socket, Mobile Registration, Card.
  4. Business governance: AML, Reconciliation, Campaign, Inventory, Report, Support.
  5. Cleanup and consistency: FAQ inclusion decision, deprecated/inactive modules, README route map sync.

Master TODO Checklist

  • [x] Update docs/README.md route list to exactly match included routers and no-prefix routes.
  • [x] Add or update a route coverage index in docs (linking every route group to its canonical doc).
  • [x] Complete endpoint inventory tables for each route group.
  • [ ] Add missing workflows and edge-case documentation for high-volume modules.
  • [ ] Reconcile docs with actual permission strings used in endpoint dependencies.
  • [ ] Standardize error response examples across all module docs.
  • [x] Resolve FAQ router inclusion/deprecation decision and document it.
  • [x] Mark inactive/deprecated endpoints clearly (ai.py, any commented route blocks).
  • [x] Perform a final route-to-doc drift check against app/api/v1/router.py before sign-off.

Verification Progress Snapshot

  • [x] Authentication (auth.py -> AUTHENTICATION.md) verified on 2026-06-28.
  • [x] Transaction (transaction.py -> TRANSACTION_PROCESSING.md) verified on 2026-06-28.
  • [x] Wallet (wallet.py -> WALLET_PAYMENT_SERVICES.md) verified on 2026-06-28.
  • [x] Loan (loan.py -> LOAN_MANAGEMENT.md) verified on 2026-06-28.
  • [x] Agent (agent.py -> AGENT_MANAGEMENT.md) verified on 2026-06-28.
  • [x] User/Role/Policy (users.py, roles.py, policy.py -> USER_ROLE_MANAGEMENT.md, POLICY_MANAGEMENT.md) verified on 2026-06-28.
  • [x] Permissions (permissions.py -> PERMISSIONS.md) verified on 2026-06-28.
  • [x] Core/Customer/Document (core.py, customer.py, document.py) verified on 2026-06-28.
  • [x] Integration/App/USSD/Notify (integration.py, app.py, ussd.py, notify.py) verified on 2026-06-28.
  • [x] AI Agent/Report/AML/Campaign/Inventory (ai_agent.py, report.py, aml.py, campaign.py, inventory.py) verified on 2026-06-28.
  • [x] Support/TOTP/Config/Reconciliation (support.py, totp.py, config.py, reconciliation.py) verified on 2026-06-28.
  • [x] Mobile Registration/Card/Socket (mobile_register.py, card.py, socket.py) verified on 2026-06-28.
  • [x] Unwired/inactive module posture documented in docs/ROUTER_WIRING_NOTES.md (faq.py, ai.py).

Quality Hardening Progress

  • [x] Added verified permission-dependency notes for AUTHENTICATION.md, TRANSACTION_PROCESSING.md, and WALLET_PAYMENT_SERVICES.md.
  • [x] Added standardized error response matrices for AUTHENTICATION.md, TRANSACTION_PROCESSING.md, and WALLET_PAYMENT_SERVICES.md.
  • [x] Added verified permission-dependency notes and standardized error response matrices for CORE_INTEGRATION.md, CUSTOMER_MANAGEMENT.md, SUPPORT_OPERATIONS.md, AML.md, RECONCILIATION.md, and CAMPAIGN_INVENTORY.md.
  • [x] Added cross-module appendix: STANDARD_ERROR_CODES.md and linked it from README.md.
  • [x] Expanded MOBILE_REGISTRATION.md with endpoint purpose map, verified service/API dependency map, workflow summary, and standardized error matrix.
  • [ ] Remaining modules can be further enriched with endpoint-level purpose/permission tables where needed.

Audit Timestamp

  • Date: 2026-06-28
  • Basis: static analysis of app/api/v1/router.py and endpoint decorators in app/api/v1/endpoints/*.py