Backend API for CarePay — a hospital cash-management system that provides virtual accounts for patients, Nomba payment integration, team management with RBAC, and automated reconciliation.
Base URL: https://carepay-be.duckdns.org
API Docs: https://carepay-be.duckdns.org/docs
| Role | Password | |
|---|---|---|
| Admin | kodiugos@gmail.com | benji918@ |
| Clerk | ugochukwub79@gmail.com | benji918@ |
| Credential | Value |
|---|---|
| Account ID | f666ef9b-888e-4799-85ce-acb505b28023 |
| Subaccount ID | 56742266-6c39-4684-8615-688846a864bd |
| Client ID | e5e85b13-f560-4643-814e-c87435dbbc15 |
| Client Secret | 8/doS7Q3w77EANpk3vpgSrc05hhOiRWp3eBs01sXyZ1AmovtZUXlmrxie+xnEF2tR4q79t0IFufMD1d4JrkT8g== |
- FastAPI — async web framework
- Tortoise ORM + Aerich — async ORM with migrations
- PostgreSQL — primary data store
- Redis — Celery broker, result backend, session store
- Celery — async task queue (reconciliation, notifications)
- Hashicorp Vault — secrets management (refresh-token storage)
- Nomba API — virtual account provisioning & payments
- SlowAPI — rate limiting
- Argon2 — password hashing
- JWT — stateless auth
- Python 3.11+
- PostgreSQL 14+
- Redis 6+
- uv (package manager)
# Install dependencies
make install
# Copy and configure environment
cp .env.example .env # or create .env from scratch
# Edit .env with your DATABASE_URL, REDIS_URL, VAULT_TOKEN, etc.
# Initialize the database (one-time)
make migrate-init # creates aerich migration tracking
make init-db # creates tables and initial migration
# Run the server
make run # http://127.0.0.1:8000| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL |
Yes | — | PostgreSQL connection string |
REDIS_URL |
No | redis://localhost:6379/0 |
Redis URL |
VAULT_URL |
Yes* | — | Hashicorp Vault address |
VAULT_TOKEN |
Yes* | — | Vault authentication token |
NOMBA_BASE_URL |
No | https://api.nomba.com |
Nomba API base URL |
JWT_SECRET |
No | change-me-in-production |
JWT signing key |
SMTP_HOST |
No | smtp.gmail.com |
Email SMTP host |
SMTP_USER |
Yes* | — | SMTP username |
SMTP_PASSWORD |
Yes* | — | SMTP password |
* Required for the corresponding feature (Vault for refresh tokens, SMTP for team invites).
make migrate # create a new migration (prompts for name)
make upgrade # apply pending migrations
make downgrade # roll back the last migration
make history # show migration historymake celery-worker # run worker only
make celery-beat # run beat scheduler only
make celery # run worker + beat togethermain.py # FastAPI app entrypoint
app/
├── core/ # shared infrastructure
│ ├── config.py # pydantic-settings
│ ├── database.py # Tortoise ORM init & TORTOISE_ORM config
│ ├── redis.py # Redis client
│ ├── vault.py # Hashicorp Vault integration
│ ├── celery.py # Celery app
│ ├── email.py # SMTP email sender
│ ├── security.py # encryption helpers
│ ├── responses.py # standardized error/response helpers
│ ├── validators.py # custom validators
│ └── retry.py # retry decorator
├── modules/
│ ├── auth/ # user registration, login, JWT
│ ├── hospitals/ # hospital profile, balance
│ ├── patients/ # patient records, virtual accounts
│ ├── payments/ # Nomba integration, invoices, transactions
│ ├── reconciliation/ # background reconciliation tasks
│ └── team_members/ # invite flow, RBAC
├── workers/
│ └── celery_worker.py # Celery app instance
├── templates/ # email templates (HTML)
├── migrations/ # Aerich migration files
└── tests/ # test suite
| Command | Description |
|---|---|
install |
Install dependencies & pre-commit hooks |
format |
Auto-format with Ruff |
lint |
Lint with Ruff |
run |
Start dev server (hot-reload on port 8000) |
test |
Run pytest suite |
migrate-init |
Initialize Aerich migration tracking |
init-db |
Create database tables |
migrate |
Create a new migration |
upgrade |
Apply pending migrations |
downgrade |
Roll back last migration |
celery |
Run Celery worker + beat |