Fluzpay

Fluzpay is a small FastAPI service for authenticated transaction management. It handles user registration/login, JWT-protected transaction CRUD, transaction filtering, summary totals, and audit logs for lifecycle changes.

It is intentionally simple: one API service, one relational database, and a thin service layer where transaction rules live.

What is inside

• FastAPI app with OpenAPI docs at /docs
• JWT auth with bcrypt password hashing
• SQLAlchemy models for users, transactions, and transaction logs
• Transaction filtering by status, type, and amount range
• Summary endpoint for per-user totals and status counts
• Docker Compose setup with Postgres and nginx
• Async API tests using httpx against the ASGI app

Architecture

The editable Excalidraw source is in docs/architecture.excalidraw.

  .------------------------------------------------------.
 /                      Client                           /
'------------------------------------------------------'
             |
             | HTTP / JSON
             v
  .------------------------------------------------------.
 /                       nginx                           /
|  proxy headers, basic hardening, rate limiting          |
'------------------------------------------------------'
             |
             v
  .------------------------------------------------------.
 /                    FastAPI app                        /
|  app/main.py                                           |
|  - CORS                                                |
|  - health/root endpoints                               |
|  - exception handlers                                  |
'------------------------------------------------------'
        |                                  |
        v                                  v
 .------------------.              .--------------------.
/ Auth router       /              / Transactions router /
| /auth/register    |              | CRUD, filters, logs |
| /auth/login       |              | summary endpoint    |
'------------------'              '--------------------'
        |                                  |
        v                                  v
 .------------------.              .--------------------.
/ app/auth.py       /              / TransactionService  /
| JWT + password    |              | business workflow   |
'------------------'              '--------------------'
        |                                  |
        '----------------. .---------------'
                         v
              .----------------------.
             / SQLAlchemy session    /
            | app/database.py        |
            '----------------------'
                         |
                         v
              .----------------------.
             / PostgreSQL            /
            | users, transactions,   |
            | transaction_logs       |
            '----------------------'

API surface

Auth:

• POST /auth/register
• POST /auth/login
• GET /auth/me

Transactions:

• POST /transactions/
• GET /transactions/
• GET /transactions/summary
• GET /transactions/{transaction_id}
• PUT /transactions/{transaction_id}
• DELETE /transactions/{transaction_id}
• GET /transactions/{transaction_id}/logs

Useful query filters on GET /transactions/:

• status=pending|completed|failed|cancelled
• transaction_type=debit|credit|transfer
• min_amount=10
• max_amount=500
• skip=0
• limit=100

Run locally

Create an environment file:

cp env.example .env

For a local Postgres run, set DATABASE_URL to your database. For a quick throwaway run you can use SQLite:

DATABASE_URL=sqlite:///./payflow.db uvicorn app.main:app --reload

Then open:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

Run with Docker

docker compose up --build

The Compose setup starts:

• db: Postgres 15
• app: FastAPI on port 8000
• nginx: reverse proxy on port 80

For a deployed setup, put TLS in front of nginx or extend nginx.conf with real certificates from your certificate manager.

Configuration

Environment variables:

Name	Purpose	Default
DATABASE_URL	SQLAlchemy database URL	local Postgres placeholder
SECRET_KEY	JWT signing secret	development placeholder
ALGORITHM	JWT algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Access token lifetime	30
CORS_ORIGINS	Comma-separated allowed origins	*
DEBUG	Enables reload when running app.main directly	True
LOG_LEVEL	Python logging level	INFO
LOG_FILE	Optional file path for structured logs	stdout when empty

Tests

python -m pytest

The tests use an in-memory SQLite database and exercise registration, login, protected routes, filters, summaries, validation, cancellation, and audit logs.

Data model

• users: login identity and profile fields
• transactions: amount, type, status, accounts, reference id, ownership
• transaction_logs: audit trail entries tied to transaction updates

Transactions start as pending. Deleting a transaction is implemented as cancellation, so the row remains available for history and logs.