DEPLOYMENT_INSTRUCTIONS.md

# Legal Dashboard OCR - Deployment Instructions

## 🚀 Quick Start

### 1. Local Development Setup

```bash
# Clone or navigate to the project
cd legal_dashboard_ocr

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export HF_TOKEN="your_huggingface_token"

# Run the application
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 2. Access the Application

- **Web Dashboard**: http://localhost:8000
- **API Documentation**: http://localhost:8000/docs
- **Health Check**: http://localhost:8000/health

## 📦 Project Structure

```
legal_dashboard_ocr/
├── README.md                    # Main documentation
├── requirements.txt             # Python dependencies
├── test_structure.py           # Structure verification
├── DEPLOYMENT_INSTRUCTIONS.md  # This file
├── app/                        # Backend application
│   ├── __init__.py
│   ├── main.py                 # FastAPI entry point
│   ├── api/                    # API routes
│   │   ├── __init__.py
│   │   ├── documents.py        # Document CRUD
│   │   ├── ocr.py             # OCR processing
│   │   └── dashboard.py       # Dashboard analytics
│   ├── services/               # Business logic
│   │   ├── __init__.py
│   │   ├── ocr_service.py     # OCR pipeline
│   │   ├── database_service.py # Database operations
│   │   └── ai_service.py      # AI scoring
│   └── models/                 # Data models
│       ├── __init__.py
│       └── document_models.py  # Pydantic schemas
├── frontend/                   # Web interface
│   ├── improved_legal_dashboard.html
│   └── test_integration.html
├── tests/                      # Test suite
│   ├── test_api_endpoints.py
│   └── test_ocr_pipeline.py
├── data/                       # Sample documents
│   └── sample_persian.pdf
└── huggingface_space/          # HF Space deployment
    ├── app.py                  # Gradio interface
    ├── Spacefile               # Deployment config
    └── README.md               # Space documentation
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# Hugging Face Token (required for OCR models)
HF_TOKEN=your_huggingface_token_here

# Database configuration (optional)
DATABASE_URL=sqlite:///legal_documents.db

# Server configuration (optional)
HOST=0.0.0.0
PORT=8000
DEBUG=true
```

### Hugging Face Token

1. Go to https://huggingface.co/settings/tokens
2. Create a new token with read permissions
3. Add it to your environment variables

## 🧪 Testing

### Run Structure Test
```bash
python test_structure.py
```

### Run API Tests
```bash
# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
python -m pytest tests/
```

### Manual Testing
```bash
# Test OCR endpoint
curl -X POST "http://localhost:8000/api/ocr/process" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@data/sample_persian.pdf"

# Test dashboard
curl "http://localhost:8000/api/dashboard/summary"
```

## 🚀 Deployment Options

### 1. Hugging Face Spaces

#### Automatic Deployment
1. Create a new Space on Hugging Face
2. Upload all files from `huggingface_space/` directory
3. Set the `HF_TOKEN` environment variable in Space settings
4. The Space will automatically build and deploy

#### Manual Deployment
```bash
# Navigate to HF Space directory
cd huggingface_space

# Install dependencies
pip install -r ../requirements.txt

# Run the Gradio app
python app.py
```

### 2. Docker Deployment

#### Create Dockerfile
```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Run the application
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

#### Build and Run
```bash
# Build Docker image
docker build -t legal-dashboard-ocr .

# Run container
docker run -p 8000:8000 \
  -e HF_TOKEN=your_token \
  legal-dashboard-ocr
```

### 3. Production Deployment

#### Using Gunicorn
```bash
# Install gunicorn
pip install gunicorn

# Run with multiple workers
gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000
```

#### Using Nginx (Reverse Proxy)
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 🔍 Troubleshooting

### Common Issues

#### 1. Import Errors
```bash
# Ensure you're in the correct directory
cd legal_dashboard_ocr

# Install dependencies
pip install -r requirements.txt

# Check Python path
python -c "import sys; print(sys.path)"
```

#### 2. OCR Model Loading Issues
```bash
# Check HF token
echo $HF_TOKEN

# Test model download
python -c "from transformers import pipeline; p = pipeline('image-to-text', 'microsoft/trocr-base-stage1')"
```

#### 3. Database Issues
```bash
# Check database file
ls -la legal_documents.db

# Reset database (if needed)
rm legal_documents.db
```

#### 4. Port Already in Use
```bash
# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

# Or use different port
uvicorn app.main:app --port 8001
```

### Performance Optimization

#### 1. Model Caching
```python
# In app/services/ocr_service.py
# Models are automatically cached by Hugging Face
# Cache location: ~/.cache/huggingface/
```

#### 2. Database Optimization
```sql
-- Add indexes for better performance
CREATE INDEX idx_documents_category ON documents(category);
CREATE INDEX idx_documents_status ON documents(status);
CREATE INDEX idx_documents_created_at ON documents(created_at);
```

#### 3. Memory Management
```python
# In app/main.py
# Configure memory limits
import gc
gc.collect()  # Force garbage collection
```

## 📊 Monitoring

### Health Check
```bash
curl http://localhost:8000/health
```

### API Documentation
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### Logs
```bash
# View application logs
tail -f logs/app.log

# View error logs
grep ERROR logs/app.log
```

## 🔒 Security

### Production Checklist
- [ ] Set `DEBUG=false` in production
- [ ] Use HTTPS in production
- [ ] Implement rate limiting
- [ ] Add authentication/authorization
- [ ] Secure file upload validation
- [ ] Regular security updates

### Environment Security
```bash
# Secure environment variables
export HF_TOKEN="your_secure_token"
export DATABASE_URL="your_secure_db_url"

# Use .env file (don't commit to git)
echo "HF_TOKEN=your_token" > .env
echo ".env" >> .gitignore
```

## 📈 Scaling

### Horizontal Scaling
```bash
# Run multiple instances
uvicorn app.main:app --host 0.0.0.0 --port 8000 &
uvicorn app.main:app --host 0.0.0.0 --port 8001 &
uvicorn app.main:app --host 0.0.0.0 --port 8002 &
```

### Load Balancing
```nginx
upstream legal_dashboard {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

server {
    listen 80;
    location / {
        proxy_pass http://legal_dashboard;
    }
}
```

## 🆘 Support

### Getting Help
1. Check the logs for error messages
2. Verify environment variables are set
3. Test with the sample PDF in `data/`
4. Check the API documentation at `/docs`

### Common Commands
```bash
# Start development server
uvicorn app.main:app --reload

# Run tests
python -m pytest tests/

# Check structure
python test_structure.py

# View API docs
open http://localhost:8000/docs
```

## 🎯 Next Steps

1. **Deploy to Hugging Face Spaces** for easy sharing
2. **Add authentication** for production use
3. **Implement user management** for multi-user support
4. **Add more OCR models** for different document types
5. **Create mobile app** for document scanning
6. **Add batch processing** for multiple documents
7. **Implement advanced analytics** and reporting

---

**Note**: This project is designed for Persian legal documents. Ensure your documents are clear and well-scanned for best OCR results.