vkluff/fast_wallet_service

Purpose and entry points

Fast Wallet Service is a Python/FastAPI financial microservice for authenticated wallet balances, deposits, transfers, transaction history, API-key access, and Paystack payment processing. The runtime entry point is main.py; serverless deployment likely enters through api/index.py under vercel.json. HTTP APIs are organized by domain in routers/auth.py, routers/wallet.py, routers/keys.py, and routers/webhook.py.

API composition and request boundary

main.py constructs the FastAPI application, applies global configuration/CORS, and mounts routers. Router modules are the public HTTP boundary: they validate request/response payloads through Pydantic schemas in schemas/auth.py, schemas/wallet.py, and schemas/keys.py, then delegate domain work rather than directly owning persistence. This supports generated OpenAPI documentation and independently evolvable endpoint groups.

Authentication and authorization

Two principal types access protected operations:

• User JWTs are issued and validated through routers/auth.py, dependencies/auth.py, and core/security.py.

• Service API keys are created, rotated, hashed, validated, and permission-scoped through routers/keys.py, core/api_key_manager.py, and dependencies/auth.py.

This authentication boundary separates user identity from machine credentials and gates wallet actions by configured permissions.

Wallet ledger and transactional domain

core/wallet_service.py is the central financial domain layer. It coordinates wallet lookup, balance mutation, recipient validation, transfers, deposits, and transaction-history behavior using persisted entities in core/models.py. routers/wallet.py exposes balance, deposit, transfer, and history APIs; schemas/wallet.py defines their contract. Transfer and balance-changing paths should retain database transaction atomicity so debit/credit and audit records cannot partially commit.

Persistence and schema evolution

core/db.py provides SQLAlchemy database setup/session access, while core/models.py defines the durable user, wallet, transaction, and API-key model boundary. The service supports development SQLite (a checked-in local.db exists) and production PostgreSQL/asyncpg based on environment configuration in core/config.py. Alembic owns database migration execution and history through alembic/env.py and alembic/versions/062f4fd5646e_add_apikey_table.py.

Payment initiation and webhook reconciliation

Deposit requests flow from routers/wallet.py to core/paystack_client.py, which integrates with Paystack to initialize payment. Paystack calls back into routers/webhook.py; this inbound trust boundary must verify its HMAC signature before invoking wallet/transaction updates. Reconciliation must be idempotent because payment providers can retry webhook delivery.

Runtime and infrastructure

The application targets Python 3.11+, FastAPI, SQLAlchemy 2 async patterns, Pydantic, Uvicorn, and JWT libraries as declared in requirements.txt. Environment-driven credentials and behavior are centralized in core/config.py, with .env.example defining expected configuration. Deployment surfaces include Vercel (vercel.json, api/index.py) and container/cloud-oriented PostgreSQL support; Paystack is the material external payment service.