README.md

metadata

sdk: docker
emoji: 👀
colorFrom: yellow
colorTo: red
pinned: true

📊 Legal Dashboard - داشبورد حقوقی

A comprehensive legal document management and analysis system built with FastAPI and Gradio, optimized for multiple deployment environments including Hugging Face Spaces.

🌟 Features

• 📄 Document Management: Upload, process, and manage legal documents (PDF, DOCX, DOC, TXT)
• 🤖 AI-Powered Analysis: Extract key information using advanced NLP models
• 🔐 Secure Authentication: JWT-based authentication with role management
• 📊 Analytics Dashboard: Real-time analytics and document insights
• 🌐 Web Scraping: Extract content from legal websites
• 🔍 Smart Search: Advanced search capabilities across documents
• 📱 Multi-Interface: Web dashboard + Gradio interface for HF Spaces
• 🌍 Multi-Language: Persian/Farsi and English support
• ☁️ Multi-Platform: Docker, HF Spaces, Local deployment

🚀 Quick Start

Option 1: Hugging Face Spaces (Recommended for Demo)

1. Fork this Space or create a new one
2. Upload all files to your space
3. Set environment variables in Space settings:

   JWT_SECRET_KEY=your-super-secret-key-here
   DATABASE_DIR=/tmp/legal_dashboard/data
   LOG_LEVEL=INFO
   

4. Launch the space - it will automatically start

Demo Credentials:

• Username: admin
• Password: admin123

Option 2: Docker Deployment

# Clone repository
git clone <your-repo-url>
cd legal-dashboard

# Build and run
docker-compose up --build

# Or with Docker only
docker build -t legal-dashboard .
docker run -p 8000:8000 legal-dashboard

Option 3: Local Development

# Install dependencies
pip install -r requirements.txt

# Setup environment
cp .env.example .env
# Edit .env with your settings

# Run application
python run.py
# Or specific interfaces:
python app.py          # Gradio interface
uvicorn app.main:app   # FastAPI only

📁 Project Structure

legal-dashboard/
├── 🚀 Deployment & Config
│   ├── run.py                  # Universal runner (All environments)
│   ├── config.py               # Configuration management
│   ├── startup_hf.py           # HF Spaces startup
│   ├── app.py                  # Gradio interface
│   ├── Dockerfile              # Docker configuration
│   ├── docker-compose.yml      # Docker Compose
│   ├── requirements.txt        # Dependencies
│   └── .env                    # Environment variables
│
├── 🏗️ Backend (FastAPI)
│   ├── app/
│   │   ├── main.py             # FastAPI application
│   │   ├── api/                # API endpoints
│   │   │   ├── auth.py         # Authentication
│   │   │   ├── documents.py    # Document management
│   │   │   ├── analytics.py    # Analytics
│   │   │   ├── scraping.py     # Web scraping
│   │   │   └── ...
│   │   ├── services/           # Business logic
│   │   │   ├── ai_service.py   # AI/ML services
│   │   │   ├── database_service.py
│   │   │   ├── ocr_service.py  # OCR processing
│   │   │   └── ...
│   │   └── models/             # Data models
│
├── 🎨 Frontend
│   ├── index.html              # Main dashboard
│   ├── documents.html          # Document management
│   ├── analytics.html          # Analytics page
│   ├── upload.html             # File upload
│   ├── js/                     # JavaScript modules
│   └── ...
│
└── 🧪 Testing & Docs
    ├── tests/                  # Test suites
    ├── docs/                   # Documentation
    └── README.md               # This file

⚙️ Configuration

Environment Variables

Variable	Default	Description
JWT_SECRET_KEY	auto-generated	JWT signing key
DATABASE_DIR	/app/data	Database directory
LOG_LEVEL	INFO	Logging level
ENVIRONMENT	production	Environment type
HF_HOME	/app/cache	ML models cache
PORT	8000/7860	Server port
WORKERS	1/4	Worker processes

Multi-Environment Support

The system automatically detects and optimizes for:

• 🤗 Hugging Face Spaces: Gradio interface, optimized resources
• 🐳 Docker: Full FastAPI with all features
• 💻 Local: Development mode with hot reload

🔧 Advanced Configuration

Custom Model Configuration

# config.py - AI Configuration
ai_config = {
    "model_name": "microsoft/trocr-small-stage1",  # HF Spaces
    "device": "cpu",  # Force CPU for compatibility
    "max_workers": 1,  # Optimize for environment
    "batch_size": 1,   # Memory optimization
}

Database Optimization

# Automatic fallback paths for different environments
database_paths = [
    "/app/data/legal_documents.db",      # Docker
    "/tmp/legal_dashboard/data/legal.db", # HF Spaces
    "./data/legal_documents.db",         # Local
    ":memory:"                           # Final fallback
]

🐛 Troubleshooting

Common Issues & Solutions

1. Permission Denied Error

   PermissionError: [Errno 13] Permission denied: '/app/database'
   

   Solution: System uses automatic fallback directories

   # Check logs for actual directory used:
   grep "📁.*directory" logs/legal_dashboard.log
   

2. bcrypt Version Error

   (trapped) error reading bcrypt version
   

   Solution: Fixed with bcrypt==4.0.1 in requirements.txt

3. Redis Connection Failed

   Redis connection failed: Error 111 connecting to localhost:6379
   

   Solution: System automatically falls back to in-memory storage

4. Model Loading Issues

   OutOfMemoryError or CUDA errors
   

   Solution: System forces CPU mode and optimizes model selection

5. Port Already in Use

   [Errno 48] Address already in use
   

   Solution: System automatically tries alternative ports

Debug Mode

# Enable debug logging
export LOG_LEVEL=DEBUG
python run.py

# Or check specific components
python -c "from config import config; print(config.get_summary())"

Health Checks

# Check system health
curl http://localhost:8000/api/health

# Expected response:
{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "ocr": "healthy",
    "ai": "healthy"
  }
}

🔒 Security

Authentication Flow

1. Registration: Create account with email/password
2. Login: JWT access token (30 min) + refresh token (7 days)
3. Authorization: Role-based access control (admin/user)
4. Session Management: Secure token storage and refresh

Security Features

• 🔐 bcrypt password hashing
• 🎫 JWT token authentication
• 🛡️ CORS protection
• 📝 Audit logging
• 🔒 Role-based permissions
• 🚫 Rate limiting (planned)

Default Credentials

⚠️ Change immediately in production:

• Username: admin
• Password: admin123

📊 API Documentation

Main Endpoints

Endpoint	Method	Description
/api/auth/login	POST	User authentication
/api/auth/register	POST	User registration
/api/documents	GET/POST	Document management
/api/ocr/process	POST	OCR processing
/api/analytics/overview	GET	Analytics data
/api/scraping/scrape	POST	Web scraping
/api/health	GET	System health

Interactive Documentation

• Swagger UI: /api/docs
• ReDoc: /api/redoc
• OpenAPI JSON: /api/openapi.json

🚀 Deployment Guide

Hugging Face Spaces

1. Create Space:

   # Go to https://huggingface.co/spaces
   # Create new Space with Gradio SDK
   

2. Upload Files:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
   cp -r legal-dashboard/* YOUR_SPACE/
   cd YOUR_SPACE
   git add .
   git commit -m "Initial deployment"
   git push
   

3. Configure Space:

   • Set JWT_SECRET_KEY in Space settings
   • Optional: Set custom domain

Docker Production

# Production docker-compose
version: "3.8"
services:
  legal-dashboard:
    build: .
    ports:
      - "80:8000"
    environment:
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - ENVIRONMENT=production
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

Kubernetes (Advanced)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: legal-dashboard
spec:
  replicas: 3
  selector:
    matchLabels:
      app: legal-dashboard
  template:
    spec:
      containers:
      - name: legal-dashboard
        image: legal-dashboard:latest
        ports:
        - containerPort: 8000
        env:
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: legal-dashboard-secrets
              key: jwt-secret

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Make changes and test thoroughly
4. Run tests: python -m pytest tests/
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Create Pull Request

Development Setup

# Clone and setup
git clone <repo-url>
cd legal-dashboard

# Install development dependencies
pip install -r requirements.txt
pip install pytest black isort mypy

# Setup pre-commit hooks
pre-commit install

# Run tests
python -m pytest tests/ -v

# Code formatting
black .
isort .

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI: Modern, fast web framework
• Gradio: Easy-to-use ML app interface
• Hugging Face: Model hosting and Spaces platform
• Transformers: State-of-the-art NLP models
• Chart.js: Beautiful charts and visualizations

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact maintainers
• Documentation: Full Docs

---

🌐 Live Demo

Try the live demo: [Your HF Space URL]

Made with ❤️ for the legal community