# vkluff/fast_wallet_service architecture

> Architecture diagram of the GitHub repository vkluff/fast_wallet_service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vkluff/fast_wallet_service
- Repository: https://github.com/vkluff/fast_wallet_service

## Overview

#### 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.

Main entry points: [`main.py`](https://github.com/vkluff/fast_wallet_service/blob/main/main.py) (FastAPI application), [`routers/wallet.py`](https://github.com/vkluff/fast_wallet_service/blob/main/routers/wallet.py) (Wallet API), [`dependencies/auth.py`](https://github.com/vkluff/fast_wallet_service/blob/main/dependencies/auth.py) (Auth dependency), [`routers/keys.py`](https://github.com/vkluff/fast_wallet_service/blob/main/routers/keys.py) (API keys API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["FastAPI application<br/>app composition<br/>[main.py]"]
  node_vercel_entry["Vercel entry<br/>serverless adapter<br/>[index.py]"]
end

subgraph group_api["HTTP API"]
  node_auth_router["Auth API<br/>router<br/>[auth.py]"]
  node_wallet_router["Wallet API<br/>router<br/>[wallet.py]"]
  node_keys_router["API keys API<br/>router<br/>[keys.py]"]
  node_webhook_router["Paystack webhook<br/>inbound router<br/>[webhook.py]"]
  node_schemas["API schemas<br/>Pydantic contracts<br/>[wallet.py]"]
end

subgraph group_domain["Domain &amp; Security"]
  node_auth_dependency{{"Auth dependency<br/>authorization boundary<br/>[auth.py]"}}
  node_security["JWT security<br/>token service<br/>[security.py]"]
  node_api_key_manager["API key manager<br/>credential service<br/>[api_key_manager.py]"]
  node_wallet_service["Wallet ledger service<br/>financial domain service<br/>[wallet_service.py]"]
  node_paystack_client["Paystack client<br/>payment gateway adapter<br/>[paystack_client.py]"]
end

subgraph group_data["Persistence"]
  node_db[("SQLAlchemy session<br/>database access<br/>[db.py]")]
  node_models["Durable models<br/>ORM entities<br/>[models.py]"]
  node_migrations["Alembic migrations<br/>schema evolution<br/>[env.py]"]
  node_database[("SQLite / PostgreSQL<br/>durable store<br/>[local.db]")]
end

subgraph group_external["External Systems"]
  node_paystack{{"Paystack<br/>payment provider"}}
end

node_vercel_entry -->|"hosts"| node_main
node_main -->|"mounts"| node_auth_router
node_main -->|"mounts"| node_wallet_router
node_main -->|"mounts"| node_keys_router
node_main -->|"mounts"| node_webhook_router
node_auth_router -->|"issues JWTs"| node_security
node_wallet_router -->|"validates payloads"| node_schemas
node_wallet_router -->|"authorizes"| node_auth_dependency
node_keys_router -->|"authorizes"| node_auth_dependency
node_auth_dependency -->|"validates JWTs"| node_security
node_auth_dependency -->|"validates keys"| node_api_key_manager
node_keys_router -->|"manages keys"| node_api_key_manager
node_wallet_router -->|"wallet operations"| node_wallet_service
node_wallet_router -->|"initiates deposit"| node_paystack_client
node_paystack_client -->|"payment initialization"| node_paystack
node_paystack -->|"signed callbacks"| node_webhook_router
node_webhook_router -->|"idempotent reconciliation"| node_wallet_service
node_wallet_service -->|"atomic sessions"| node_db
node_db -->|"persists"| node_models
node_models -->|"stored in"| node_database
node_migrations -->|"evolves schema"| node_database

click node_main "https://github.com/vkluff/fast_wallet_service/blob/main/main.py"
click node_vercel_entry "https://github.com/vkluff/fast_wallet_service/blob/main/api/index.py"
click node_auth_router "https://github.com/vkluff/fast_wallet_service/blob/main/routers/auth.py"
click node_wallet_router "https://github.com/vkluff/fast_wallet_service/blob/main/routers/wallet.py"
click node_keys_router "https://github.com/vkluff/fast_wallet_service/blob/main/routers/keys.py"
click node_webhook_router "https://github.com/vkluff/fast_wallet_service/blob/main/routers/webhook.py"
click node_schemas "https://github.com/vkluff/fast_wallet_service/blob/main/schemas/wallet.py"
click node_auth_dependency "https://github.com/vkluff/fast_wallet_service/blob/main/dependencies/auth.py"
click node_security "https://github.com/vkluff/fast_wallet_service/blob/main/core/security.py"
click node_api_key_manager "https://github.com/vkluff/fast_wallet_service/blob/main/core/api_key_manager.py"
click node_wallet_service "https://github.com/vkluff/fast_wallet_service/blob/main/core/wallet_service.py"
click node_paystack_client "https://github.com/vkluff/fast_wallet_service/blob/main/core/paystack_client.py"
click node_db "https://github.com/vkluff/fast_wallet_service/blob/main/core/db.py"
click node_models "https://github.com/vkluff/fast_wallet_service/blob/main/core/models.py"
click node_migrations "https://github.com/vkluff/fast_wallet_service/blob/main/alembic/env.py"
click node_database "https://github.com/vkluff/fast_wallet_service/blob/main/local.db"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_vercel_entry toneBlue
class node_auth_router,node_wallet_router,node_keys_router,node_webhook_router,node_schemas toneAmber
class node_auth_dependency,node_security,node_api_key_manager,node_wallet_service,node_paystack_client toneMint
class node_db,node_models,node_migrations,node_database toneRose
class node_paystack toneIndigo
```

## Components

### Runtime

- [FastAPI application](https://github.com/vkluff/fast_wallet_service/blob/main/main.py): app composition · Configures CORS and mounts domain routers. · `main.py`
- [Vercel entry](https://github.com/vkluff/fast_wallet_service/blob/main/api/index.py): serverless adapter · `api/index.py`

### HTTP API

- [Auth API](https://github.com/vkluff/fast_wallet_service/blob/main/routers/auth.py): router · Issues and validates user JWT access. · `routers/auth.py`
- [Wallet API](https://github.com/vkluff/fast_wallet_service/blob/main/routers/wallet.py): router · Exposes balances, deposits, transfers, and history. · `routers/wallet.py`
- [API keys API](https://github.com/vkluff/fast_wallet_service/blob/main/routers/keys.py): router · `routers/keys.py`
- [Paystack webhook](https://github.com/vkluff/fast_wallet_service/blob/main/routers/webhook.py): inbound router · Verifies callback trust before reconciliation. · `routers/webhook.py`
- [API schemas](https://github.com/vkluff/fast_wallet_service/blob/main/schemas/wallet.py): Pydantic contracts · `schemas/wallet.py`

### Domain & Security

- [Auth dependency](https://github.com/vkluff/fast_wallet_service/blob/main/dependencies/auth.py): authorization boundary · Authenticates JWTs and scoped service keys. · `dependencies/auth.py`
- [JWT security](https://github.com/vkluff/fast_wallet_service/blob/main/core/security.py): token service · `core/security.py`
- [API key manager](https://github.com/vkluff/fast_wallet_service/blob/main/core/api_key_manager.py): credential service · Hashes, rotates, validates, and scopes keys. · `core/api_key_manager.py`
- [Wallet ledger service](https://github.com/vkluff/fast_wallet_service/blob/main/core/wallet_service.py): financial domain service · Coordinates atomic balance changes and transaction audit records. · `core/wallet_service.py`
- [Paystack client](https://github.com/vkluff/fast_wallet_service/blob/main/core/paystack_client.py): payment gateway adapter · Initializes deposit payments. · `core/paystack_client.py`

### Persistence

- [SQLAlchemy session](https://github.com/vkluff/fast_wallet_service/blob/main/core/db.py): database access · `core/db.py`
- [Durable models](https://github.com/vkluff/fast_wallet_service/blob/main/core/models.py): ORM entities · Users, wallets, transactions, and API keys. · `core/models.py`
- [Alembic migrations](https://github.com/vkluff/fast_wallet_service/blob/main/alembic/env.py): schema evolution · `alembic/env.py`
- [SQLite / PostgreSQL](https://github.com/vkluff/fast_wallet_service/blob/main/local.db): durable store · SQLite for development and PostgreSQL for production. · `local.db`

### External Systems

- **Paystack**: payment provider

## Connections

- Vercel entry → FastAPI application: hosts
- FastAPI application → Auth API: mounts
- FastAPI application → Wallet API: mounts
- FastAPI application → API keys API: mounts
- FastAPI application → Paystack webhook: mounts
- Auth API → JWT security: issues JWTs
- Wallet API → API schemas: validates payloads
- Wallet API → Auth dependency: authorizes
- API keys API → Auth dependency: authorizes
- Auth dependency → JWT security: validates JWTs
- Auth dependency → API key manager: validates keys
- API keys API → API key manager: manages keys
- Wallet API → Wallet ledger service: wallet operations
- Wallet API → Paystack client: initiates deposit
- Paystack client → Paystack: payment initialization
- Paystack → Paystack webhook: signed callbacks
- Paystack webhook → Wallet ledger service: idempotent reconciliation
- Wallet ledger service → SQLAlchemy session: atomic sessions
- SQLAlchemy session → Durable models: persists
- Durable models → SQLite / PostgreSQL: stored in
- Alembic migrations → SQLite / PostgreSQL: evolves schema