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

```bash
# 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

```python
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:

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

## Getting Started

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

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

3. Run the application:
   ```bash
   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:

```bash
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