# Quick Start Guide

Get up and running with STUPA PDF API in 5 minutes!

## Prerequisites

- Docker and Docker Compose installed
- Git installed
- 5 minutes of your time

## 🚀 Quick Setup

### 1. Clone and Navigate

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

### 2. Generate Configuration

```bash
# Make the script executable
chmod +x scripts/create-env.sh

# Run the configuration script
./scripts/create-env.sh
```

Just press Enter to accept all defaults for a quick local setup.

### 3. Start Everything

```bash
docker compose up -d
```

Wait about 30 seconds for all services to start.

### 4. Verify It's Working

```bash
# Check all services are running
docker compose ps

# Test the API
curl http://localhost:8000/

# Should return: {"message":"STUPA PDF API"}
```

## 🎯 Your First Application

### Using the Web Interface

1. **Open the Frontend**
   - Navigate to http://localhost:3000
   - You'll see the STUPA PDF application interface

2. **Upload a PDF Form**
   - Click "Upload PDF" or drag and drop a PDF form
   - The system will parse and extract data automatically

3. **Review Application Data**
   - Check the extracted information
   - Edit any fields if needed
   - Add comparison offers for cost positions

4. **Save Your Work**
   - Note the Application ID (e.g., "25-0001")
   - Save the Application Key securely (shown once!)

### Using the API Directly

```bash
# Upload a PDF and create application
curl -X POST "http://localhost:8000/upload" \
  -F "file=@your-form.pdf" \
  -F "form_type=pa_form"

# Response includes:
# - pa_id: Your application ID
# - pa_key: Your access key (save this!)
```

## 📝 Common Tasks

### View Your Application

```bash
# Using the web interface
http://localhost:3000/applications/YOUR_PA_ID?key=YOUR_PA_KEY

# Using the API
curl "http://localhost:8000/applications/YOUR_PA_ID?format=json" \
  -H "X-PA-KEY: YOUR_PA_KEY"
```

### Generate Filled PDF

```bash
# Download filled PDF
curl "http://localhost:8000/applications/YOUR_PA_ID?format=pdf" \
  -H "X-PA-KEY: YOUR_PA_KEY" \
  -o filled-form.pdf
```

### Add Attachments

```bash
# Upload an attachment
curl -X POST "http://localhost:8000/applications/YOUR_PA_ID/attachments" \
  -H "X-PA-KEY: YOUR_PA_KEY" \
  -F "file=@receipt.pdf"
```

### Manage Comparison Offers

Use the web interface to:
1. Click on any cost position
2. Add at least 3 comparison offers
3. Select your preferred offer
4. Save changes

## 🛠️ Quick Admin Tasks

### Access the Database

1. Open http://localhost:8080 (Adminer)
2. Login with:
   - System: MySQL
   - Server: `db`
   - Username: `root`
   - Password: (from your .env file)
   - Database: `stupa`

### View API Documentation

- **Interactive Docs**: http://localhost:8000/docs
- **Alternative Docs**: http://localhost:8000/redoc

### Check Logs

```bash
# All services
docker compose logs -f

# Specific service
docker compose logs -f api
docker compose logs -f frontend
docker compose logs -f db
```

## 🔧 Quick Troubleshooting

### Services Won't Start

```bash
# Check for port conflicts
docker compose ps

# Restart everything
docker compose restart

# Full reset
docker compose down
docker compose up -d
```

### Can't Access Frontend

1. Check if port 3000 is already in use
2. Wait 30 seconds after starting services
3. Try http://127.0.0.1:3000 instead

### API Returns 429 (Too Many Requests)

The API has rate limiting. Default: 60 requests/minute per IP.

### Lost Application Key

Application keys cannot be recovered. You'll need to:
1. Use the master key (from .env) for admin access
2. Or create a new application

## 📚 Next Steps

Now that you're up and running:

1. **Explore the Frontend**: Try all features in the web interface
2. **Read API Docs**: Check http://localhost:8000/docs
3. **Customize Settings**: Edit `.env` for your needs
4. **Add Test Data**: Create sample applications
5. **Plan Deployment**: See [Deployment Guide](./DEPLOYMENT.md)

## 🆘 Getting Help

- Check [FAQ](./FAQ.md) for common questions
- See [Troubleshooting Guide](./TROUBLESHOOTING.md) for issues
- Review [API Reference](./API_REFERENCE.md) for integration

---

**Congratulations!** 🎉 You now have a working STUPA PDF API system!