Delphi Database

A legal case management database application built with FastAPI, SQLAlchemy, and modern Python practices.

Database Configuration

The application uses SQLAlchemy ORM with support for multiple database backends.

Environment Variables

Configure your database connection using environment variables:

# SQLite (default for development)
DATABASE_URL=sqlite:///./delphi.db

# PostgreSQL (production example)
DATABASE_URL=postgresql://username:password@localhost:5432/delphi_db

# MySQL (alternative)
DATABASE_URL=mysql://username:password@localhost:3306/delphi_db

Database Models

The application includes the following models:

• User: Authentication and user management
• Client: Client/contact information
• Phone: Phone numbers linked to clients
• Case: Legal cases with unique file numbers
• Transaction: Financial transactions for cases
• Document: Case-related documents
• Payment: Payment records for cases

Database Connection Management

The app/database.py module provides:

• Database engine configuration with connection pooling and error handling
• Session management with automatic cleanup via FastAPI dependency injection
• Table creation utilities for application startup
• Connection health monitoring via the /health endpoint

Usage Examples

Basic Application Startup

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
from app.database import get_db

@app.get("/clients/")
async def get_clients(db: Session = Depends(get_db)):
    # Use the database session
    return db.query(Client).all()

Health Check

The /health endpoint verifies database connectivity:

curl http://localhost:8000/health
# {"status": "healthy", "database": "connected", "users": 0}

Getting Started

1. Install dependencies:

   pip install -r requirements.txt
   

2. Configure your database in environment variables (see .env file)

3. Run the application:

   uvicorn app.main:app --reload
   

4. Access the API at http://localhost:8000

API JSON Lists and Sorting

The following list endpoints return standardized JSON with a shared pagination envelope and Pydantic models:

• GET /api/rolodex → items: ClientOut[]
• GET /api/files → items: CaseOut[]
• GET /api/ledger → items: TransactionOut[]

Common query params:

• page (>=1), page_size (1..100 or 200 for ledger)
• sort_by (endpoint-specific whitelist)
• sort_dir (asc | desc)

If sort_by is invalid or sort_dir is not one of asc|desc, the API returns 400 with details. Dates are ISO-8601 strings, and nulls are preserved as null.

Authentication: Unauthenticated requests to /api/* return a JSON 401 with { "detail": "Unauthorized" }.

Sorting whitelists

• /api/rolodex: id, rolodex_id, last_name, first_name, company, created_at
• /api/files: file_no, status, case_type, description, open_date, close_date, created_at, client_last_name, client_first_name, client_company, id
• /api/ledger: transaction_date, item_no, id, amount, billed, t_code, t_type_l, employee_number, case_file_no, case_id

Docker smoke script

A simple curl-based smoke script is available:

docker compose up -d --build
docker compose exec delphi-db bash -lc "bash scripts/smoke.sh"

Note: For authenticated API calls, log in at /login via the browser to create a session cookie, then copy your session cookie to a cookies.txt file for curl usage.

Project Structure

app/
├── main.py          # FastAPI application entry point
├── database.py      # Database configuration and session management
├── models.py        # SQLAlchemy models
└── templates/       # HTML templates

Development

• Database tables are automatically created on application startup
• Use the health check endpoint to verify database connectivity
• Environment variables control database configuration (never hardcode credentials)
• SQLAlchemy provides type-safe database operations with relationship management