stupa-pdf-api/README.md

STUPA PDF API

A comprehensive system for managing student parliament (STUPA) funding applications with PDF processing, form generation, and document management capabilities.

🚀 Features

• PDF Processing: Parse and extract structured data from uploaded PDF forms
• Dynamic Form Generation: Generate filled PDF forms from application data
• Document Management: Upload and manage supporting documents (up to 30 files, 100MB total)
• Comparison Offers: Manage cost comparison requirements with 3-offer validation
• Secure Access: Application-specific keys and master key authentication
• Modern UI: React-based frontend with Material-UI components
• API Documentation: Auto-generated OpenAPI/Swagger documentation
• Rate Limiting: Configurable rate limits for API protection
• Database UI: Integrated Adminer for database management
• LaTeX Integration: Integrated LaTeX templates for QSM and VSM forms

📋 Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• Git
• 4GB RAM minimum (8GB recommended)
• 2GB free disk space

🏗️ Project Structure

stupa-pdf-api/
├── backend/                 # FastAPI backend application
│   ├── src/                # Source code
│   │   ├── migrations/     # Database migrations
│   │   ├── service_api.py  # Main API application
│   │   ├── pdf_filler.py   # PDF generation
│   │   ├── pdf_to_struct.py # PDF parsing
│   │   └── ...
│   ├── assets/             # PDF templates
│   ├── latex-templates/    # LaTeX source (git submodule)
│   ├── latex-qsm/         # QSM LaTeX worktree
│   ├── latex-vsm/         # VSM LaTeX worktree
│   ├── requirements.txt    # Python dependencies
│   └── Dockerfile         # Backend container definition
├── frontend/              # React frontend application
│   ├── src/              # Source code
│   ├── public/           # Static assets
│   ├── package.json      # Node dependencies
│   ├── nginx.conf        # Nginx configuration
│   └── Dockerfile        # Frontend container definition
├── docs/                 # Documentation
│   ├── README.md         # Documentation index
│   ├── ARCHITECTURE.md   # System architecture
│   ├── API_REFERENCE.md  # API documentation
│   └── ...
├── scripts/              # Helper scripts
│   ├── create-env.sh     # Environment setup script
│   └── dev.sh           # Development helper script
├── docker-compose.yml    # Multi-container orchestration
└── README.md            # This file

⚡ Quick Start

1. Clone the Repository

git clone https://github.com/your-org/stupa-pdf-api.git
cd stupa-pdf-api

2. Setup Environment

# Make scripts executable
chmod +x scripts/*.sh

# Create .env file with secure defaults
./scripts/create-env.sh

3. Start Services

docker compose up -d

4. Access the Application

• Frontend: http://localhost:3000
• API Docs: http://localhost:8000/docs
• Database UI: http://localhost:8080

🛠️ Development

Using the Development Script

# Start all services
./scripts/dev.sh start

# View logs
./scripts/dev.sh logs api

# Open shell in container
./scripts/dev.sh shell frontend

# Run database migrations
./scripts/dev.sh migrate

# More commands
./scripts/dev.sh help

Manual Development Setup

Backend Development

cd backend
python -m venv venv
source venv/bin/activate  # Linux/macOS
pip install -r requirements.txt
uvicorn src.service_api:app --reload

Frontend Development

cd frontend
npm install
npm run dev

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Documentation Index
• Architecture Overview
• Installation Guide
• Quick Start Guide
• API Reference
• Development Guide
• PDF Integration

🔧 Configuration

Key environment variables:

# Database
MYSQL_DB=stupa
MYSQL_USER=stupa
MYSQL_PASSWORD=<generated>

# Authentication
MASTER_KEY=<generated>

# Rate Limiting
RATE_IP_PER_MIN=60
RATE_KEY_PER_MIN=30

# Application
TZ=Europe/Berlin

See Configuration Guide for all options.

🗄️ Database Migrations

Run migrations after setup:

./scripts/dev.sh migrate

Or manually:

docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_attachments_tables.sql
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_comparison_offers_tables.sql
# ... other migrations

🧪 Testing

# Run all tests
./scripts/dev.sh test

# Run linters
./scripts/dev.sh lint

# Format code
./scripts/dev.sh format

🚢 Deployment

See Deployment Guide for production deployment instructions.

Basic Production Setup

1. Use environment-specific .env file
2. Enable SSL/TLS termination
3. Configure proper domain names
4. Set up backup procedures
5. Monitor logs and metrics

🔒 Security

• Application-specific access keys
• Master key for admin access
• Rate limiting per IP and key
• Input validation and sanitization
• SQL injection prevention via ORM
• XSS protection in React
• Secure password hashing

See Security Guide for best practices.

📊 API Endpoints

Key endpoints:

• POST /upload - Upload PDF and create application
• GET /applications/{id} - Get application data
• POST /applications/{id}/attachments - Upload attachments
• GET /applications/{id}/costs/{index}/offers - Get comparison offers
• PUT /applications/{id} - Update application

Full API documentation available at http://localhost:8000/docs when running.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

See Contributing Guide for details.

📝 License

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

🆘 Support

• Check the FAQ
• Review Troubleshooting Guide
• Create an issue for bugs or features
• Contact the development team

🏆 Acknowledgments

• Built with FastAPI, React, and MySQL
• PDF processing powered by PyPDF2 and ReportLab
• UI components from Material-UI

---

Version: 1.0.0
Last Updated: 2024