delphi-database/README.md

Delphi Consulting Group Database System

A modern Python web application built with FastAPI to replace the legacy Pascal-based database system. This system maintains the familiar keyboard shortcuts and workflows while providing a robust, modular backend with a clean web interface.

🏢 Company Information

Delphi Consulting Group Inc.
Modern database system for legal practice management, financial tracking, and document management.

🎯 Project Goals

• Replace legacy Pascal system with modern, maintainable technology
• Preserve keyboard shortcuts for user familiarity
• Fully modular system - easy to add/remove sections
• Backend-first approach with solid API endpoints
• Simple HTML with minimal JavaScript - prioritize reliability
• Single SQLite file for easy backup/restore

🛠️ Technology Stack

• Backend: Python 3.12, FastAPI, SQLAlchemy 2.0+
• Database: SQLite (single file)
• Frontend: Jinja2 templates, Bootstrap 5.3, vanilla JavaScript
• Authentication: JWT with bcrypt password hashing
• Validation: Pydantic v2

📊 Database Structure

Based on analysis of legacy Pascal system:

Core Tables

1. ROLODEX - Customer/client information and contact details
2. PHONE - Phone numbers linked to customers
3. FILES - Legal cases/files with financial tracking
4. LEDGER - Financial transactions per case
5. QDROS - Legal documents (Qualified Domestic Relations Orders)
6. USERS - System authentication and authorization

⌨️ Keyboard Shortcuts

Maintains legacy system shortcuts for user familiarity:

Navigation

• Alt+C - Customers/Rolodex
• Alt+F - File Cabinet
• Alt+L - Ledger/Financial
• Alt+D - Documents/QDROs
• Alt+A - Admin Panel
• Ctrl+F - Global Search

Forms

• Ctrl+N - New Record
• Ctrl+S - Save
• F9 - Edit Mode
• F2 - Complete/Save
• F8 - Clear/Cancel
• Del - Delete Record
• Esc - Cancel/Close

Legacy Functions

• F1 - Help/Shortcuts
• F10 - Menu
• Alt+M - Memo/Notes
• Alt+T - Time Tracker
• Alt+B - Balance Summary
• +/- - Change dates by day

🚀 Quick Start

Option 1: Docker (Recommended)

# Clone repository
git clone <repository-url>
cd delphi-database

# Set up secure configuration
python scripts/setup-security.py

# Development mode
docker-compose -f docker-compose.dev.yml up

# Production mode
docker-compose up -d

Option 2: Local Installation

# Install dependencies
pip install -r requirements.txt

# Create database and admin user
python create_admin.py

# Run application
python -m uvicorn app.main:app --reload

The application will be available at: http://localhost:6920

📖 For detailed Docker deployment instructions, see DOCKER.md

📁 Project Structure

delphi-database/
├── app/
│   ├── main.py              # FastAPI application entry point
│   ├── config.py            # Configuration settings
│   ├── models/              # SQLAlchemy database models
│   │   ├── user.py          # User authentication
│   │   ├── rolodex.py       # Customer/phone models  
│   │   ├── files.py         # File cabinet model
│   │   ├── ledger.py        # Financial transactions
│   │   └── qdro.py          # Legal documents
│   ├── api/                 # API route handlers
│   │   ├── auth.py          # Authentication endpoints
│   │   ├── customers.py     # Customer management
│   │   ├── files.py         # File management
│   │   ├── financial.py     # Ledger/financial
│   │   ├── documents.py     # Document management
│   │   ├── search.py        # Search functionality
│   │   └── admin.py         # Admin functions
│   ├── auth/                # Authentication system
│   ├── database/            # Database configuration
│   └── import_export/       # Data import/export utilities
├── templates/               # Jinja2 HTML templates
│   ├── base.html           # Base template with nav/shortcuts
│   └── dashboard.html      # Main dashboard
├── static/                 # Static files (CSS, JS, images)
│   ├── css/main.css        # Main stylesheet
│   ├── js/keyboard-shortcuts.js  # Keyboard shortcut system
│   └── js/main.js          # Main JavaScript utilities
├── old database/           # Legacy Pascal files (reference)
├── uploads/                # File uploads
├── backups/                # Database backups
├── requirements.txt        # Python dependencies
├── create_admin.py         # Admin user creation script
└── README.md              # This file

🔧 API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - Register user (admin only)
• GET /api/auth/me - Current user info

Customers (Rolodex)

• GET /api/customers/ - List customers
• POST /api/customers/ - Create customer
• GET /api/customers/{id} - Get customer details
• PUT /api/customers/{id} - Update customer
• DELETE /api/customers/{id} - Delete customer
• GET /api/customers/{id}/phones - Get phone numbers
• POST /api/customers/{id}/phones - Add phone number

Files

• GET /api/files/ - List files
• POST /api/files/ - Create file
• GET /api/files/{file_no} - Get file details
• PUT /api/files/{file_no} - Update file
• DELETE /api/files/{file_no} - Delete file

Financial (Ledger)

• GET /api/financial/ledger/{file_no} - Get ledger entries
• POST /api/financial/ledger/ - Create transaction
• PUT /api/financial/ledger/{id} - Update transaction
• DELETE /api/financial/ledger/{id} - Delete transaction
• GET /api/financial/reports/{file_no} - Financial reports

Documents (QDROs)

• GET /api/documents/qdros/{file_no} - Get QDROs for file
• POST /api/documents/qdros/ - Create QDRO
• GET /api/documents/qdros/{file_no}/{id} - Get specific QDRO
• PUT /api/documents/qdros/{file_no}/{id} - Update QDRO
• DELETE /api/documents/qdros/{file_no}/{id} - Delete QDRO

Search

• GET /api/search/customers?q={query} - Search customers
• GET /api/search/files?q={query} - Search files
• GET /api/search/global?q={query} - Global search

Admin

• GET /api/admin/health - System health check
• GET /api/admin/stats - System statistics
• POST /api/admin/import/csv - Import CSV data
• GET /api/admin/export/{table} - Export table data
• GET /api/admin/backup/download - Download database backup

🔒 Authentication

• Session-based JWT authentication
• Role-based access (User/Admin)
• Password hashing with bcrypt
• Token expiration and refresh

🗄️ Data Management

• CSV import/export functionality
• Database backup and restore
• Data validation and error handling
• Automatic financial calculations (matching legacy system)

⚙️ Configuration

Environment variables (create .env file):

# Database
DATABASE_URL=sqlite:///./delphi_database.db

# Security  
SECRET_KEY=your-secret-key-change-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Application
DEBUG=False
APP_NAME=Delphi Consulting Group Database System

📋 Development Tasks

Phase 1 - Foundation ✅

• Project structure setup
• SQLAlchemy models based on legacy system
• Authentication system
• Core FastAPI application

Phase 2 - API Development ✅

• Customer management endpoints
• File management endpoints
• Financial/ledger endpoints
• Document management endpoints
• Search functionality
• Admin endpoints

Phase 3 - Frontend (In Progress)

• Base HTML template with keyboard shortcuts
• Dashboard interface
• Customer management UI
• File management UI
• Financial interface
• Document management UI
• Search interface
• Admin interface

Phase 4 - Data Migration

• Legacy .SC file parser
• Data cleaning and validation
• Migration scripts
• Data verification tools

Phase 5 - Advanced Features

• Financial calculations (matching legacy Tally_Ledger)
• Report generation
• Document templates
• Time tracking system
• Backup automation

🧪 Testing

# Run tests (when implemented)
pytest

# Run with coverage
pytest --cov=app tests/

🚢 Deployment

Docker Deployment (Recommended)

# Build and start services
docker-compose up -d

# With Nginx reverse proxy
docker-compose --profile production up -d

# Check status
docker-compose ps

Traditional Deployment

# With gunicorn for production
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

📖 Complete deployment guide: DOCKER.md

🛡️ Security & Git Best Practices

🚨 NEVER Commit These Files:

• .env - Contains secrets, passwords, API keys
• Database files - *.db, *.sqlite, delphi_database.db
• Backup files - backups/, *.backup, *.dump
• Upload files - uploads/, user documents
• SSL certificates - *.pem, *.key, *.crt
• Local configs - *-local.*, config.local.py

✅ Repository Security:

• Use python scripts/setup-security.py for secure configuration
• Install Git hooks: ./scripts/install-git-hooks.sh
• Review .gitignore before committing
• Never commit real customer data
• Rotate secrets if accidentally committed
• Use environment variables for all sensitive data

🔒 Git Hooks Protection:

The pre-commit hook automatically blocks commits containing:

• Environment files (.env)
• Database files (*.db, *.sqlite)
• Backup files (backups/, *.backup)
• SSL certificates and keys (*.pem, *.key)
• Upload directories with user files
• Large files that may contain sensitive data

🤝 Contributing

1. Follow the modular architecture principles
2. Maintain keyboard shortcut compatibility
3. Preserve legacy system workflows
4. Ensure comprehensive error handling
5. Document all API changes
6. Review security checklist before commits

📄 License

Proprietary software for Delphi Consulting Group Inc.

📞 Support

For technical support or questions about this system, contact the development team.

---

Built with ❤️ for Delphi Consulting Group Inc.