134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# 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
|