stupa-pdf-api/docs/QUICK_START.md

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

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

2. Generate Configuration

# 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

docker compose up -d

Wait about 30 seconds for all services to start.

4. Verify It's Working

# 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

# 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

# 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

# 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

# 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

# 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

# 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

🆘 Getting Help

• Check FAQ for common questions
• See Troubleshooting Guide for issues
• Review API Reference for integration

---

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