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

## 📋 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
│   ├── 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
```bash
git clone https://github.com/your-org/stupa-pdf-api.git
cd stupa-pdf-api
```

### 2. Setup Environment
```bash
# Make scripts executable
chmod +x scripts/*.sh

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

### 3. Start Services
```bash
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
```bash
# 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
```bash
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
```bash
cd frontend
npm install
npm run dev
```

## 📚 Documentation

Comprehensive documentation is available in the `/docs` directory:

- [Documentation Index](./docs/README.md)
- [Architecture Overview](./docs/ARCHITECTURE.md)
- [Installation Guide](./docs/INSTALLATION.md)
- [Quick Start Guide](./docs/QUICK_START.md)
- [API Reference](./docs/API_REFERENCE.md)
- [Development Guide](./docs/DEVELOPMENT.md)

## 🔧 Configuration

Key environment variables:

```env
# 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](./docs/CONFIGURATION.md) for all options.

## 🗄️ Database Migrations

Run migrations after setup:

```bash
./scripts/dev.sh migrate
```

Or manually:
```bash
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

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

# Run linters
./scripts/dev.sh lint

# Format code
./scripts/dev.sh format
```

## 🚢 Deployment

See [Deployment Guide](./docs/DEPLOYMENT.md) 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](./docs/SECURITY.md) 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](./docs/CONTRIBUTING.md) for details.

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- Check the [FAQ](./docs/FAQ.md)
- Review [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
- 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