Finance Dashboard API

REST backend for a finance dashboard: users and roles, financial records (CRUD + filters), aggregated dashboard data, and JWT-based access control.

Stack

• Python 3.12+
• FastAPI
• SQLAlchemy 2.x
• SQLite (file finance.db by default; configurable via DATABASE_URL)

Quick start

cd zoryn
python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
.\.venv\Scripts\uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

• Interactive docs: http://127.0.0.1:8000/docs
• Health: http://127.0.0.1:8000/health

On first startup, if no users exist, an admin user is created from environment variables (see below).

Configuration

Optional .env (or real environment variables):

Variable	Default	Description
SECRET_KEY	(dev placeholder)	JWT signing secret; change in any shared or production use
ACCESS_TOKEN_EXPIRE_MINUTES	1440	Bearer token lifetime
DATABASE_URL	sqlite:///./finance.db	SQLAlchemy URL
SEED_ADMIN_EMAIL	admin@example.com	First-run admin email
SEED_ADMIN_PASSWORD	ChangeMe123!	First-run admin password

Roles and access control

Role	Capabilities
viewer	Read dashboard summaries and trends only (/api/v1/dashboard/*). Cannot list or mutate records.
analyst	Everything viewer can do, plus read financial records (GET /api/v1/records). Cannot create, update, or delete records.
admin	Full access: user management, record CRUD (create/update/soft delete), and optional include_deleted=true on record listing.

Inactive users cannot authenticate or call protected routes.

Authentication

1. POST /api/v1/auth/login with JSON body: { "email", "password" }
2. Use returned access_token as header: Authorization: Bearer <token>
3. GET /api/v1/auth/me returns the current user.

API overview (prefix /api/v1)

Auth

• POST /auth/login — obtain JWT
• GET /auth/me — current profile

Users (admin only)

• POST /users — create user (email, password, role)
• GET /users — list users
• GET /users/{id} — get user
• PATCH /users/{id} — update role, is_active, optional password (admin cannot deactivate self)

Financial records

• POST /records — create (admin)
• GET /records — list with pagination and filters: skip, limit, type (income | expense), category (substring, case-insensitive), date_from, date_to. Admins may pass include_deleted=true.
• GET /records/{id} — detail (analyst, admin)
• PATCH /records/{id} — update (admin)
• DELETE /records/{id} — soft delete (admin)

Dashboard (viewer, analyst, admin)

• GET /dashboard/summary — totals, net balance, count, category breakdown; optional date_from, date_to
• GET /dashboard/recent — recent non-deleted records (limit 1–100)
• GET /dashboard/trends/monthly — months (1–36), SQLite strftime buckets
• GET /dashboard/trends/weekly — weeks (1–52), weeks start Monday

Aggregations exclude soft-deleted records.

Data model (assumptions)

• Single-tenant: all records belong to one logical organization; summaries are global, not per-user.
• Audit: created_by_id stores the admin who created the record (nullable for legacy rows).
• Soft delete: is_deleted hides records from default queries and dashboard math; admins can still list them with include_deleted=true.

Validation and errors

• Request bodies are validated with Pydantic; failures return 422 with detail (field errors) and message.
• Auth failures: 401; forbidden role: 403; not found: 404; duplicate email: 409; bad business state: 400 with a clear detail string.

Tests

.\.venv\Scripts\python -m pytest tests/ -v

Tests use an isolated SQLite file under tests/pytest_finance.db (removed when conftest runs).

Tradeoffs

• SQLite and JWT in settings are chosen for a small, reviewable assignment; swap DATABASE_URL and secrets for a real deployment.
• Monthly/weekly trend SQL uses SQLite date functions; another database would need dialect-specific grouping.
• Password hashing uses bcrypt directly (no passlib) for compatibility with current bcrypt releases.