stupa-pdf-api/docs/ARCHITECTURE.md

Architecture Overview

System Architecture

The STUPA PDF API is built using a microservices architecture with clear separation of concerns between the frontend, backend, and database layers.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│    Frontend     │────▶│   API Gateway   │────▶│     Backend     │
│   (React/TS)    │     │    (Nginx)      │     │   (FastAPI)     │
│                 │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                          │
                                                          ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │                 │     │                 │
                        │     Database    │     │   File Storage  │
                        │     (MySQL)     │     │   (Base64 DB)   │
                        │                 │     │                 │
                        └─────────────────┘     └─────────────────┘

Components

Frontend (React Application)

• Technology: React 18 with TypeScript
• State Management: With State
• UI Framework: Material-UI
• Build Tool: Vite
• Features:
  • Single Page Application (SPA)
  • Responsive design
  • Real-time form validation
  • File upload management
  • PDF preview capabilities

API Gateway (Nginx)

• Purpose: Reverse proxy and static file serving
• Features:
  • Route /api/* requests to backend
  • Serve static frontend assets
  • Handle CORS
  • SSL termination (production)
  • Request buffering
  • Gzip compression

Backend (FastAPI)

• Framework: FastAPI (Python 3.11)
• ORM: SQLAlchemy
• PDF Processing: PyPDF2, ReportLab
• Features:
  • RESTful API design
  • Automatic API documentation
  • Request validation
  • Rate limiting
  • Authentication middleware
  • PDF parsing and generation

Database (MySQL)

• Version: MySQL 8.0
• Character Set: utf8mb4
• Features:
  • Relational data model
  • Foreign key constraints
  • Indexes for performance
  • Transaction support

Data Flow

Application Creation Flow

1. User uploads PDF → Frontend
2. Frontend sends PDF to API → POST /upload
3. Backend parses PDF → Extracts structured data
4. Backend creates application → Stores in database
5. Backend returns application ID and key
6. Frontend redirects to application view

PDF Generation Flow

1. User requests PDF → GET /applications/{id}?format=pdf
2. Backend loads application data
3. Backend fills PDF template
4. Backend returns filled PDF
5. Frontend displays/downloads PDF

Security Architecture

Authentication Layers

1. Application Key (X-PA-KEY)

   • Generated per application
   • Allows read/write access to specific application
   • Stored as SHA-256 hash

2. Master Key (X-MASTER-KEY)

   • Environment variable
   • Full admin access
   • Never exposed to frontend

Security Features

• Rate limiting per IP and per key
• SQL injection prevention (ORM)
• XSS protection (React)
• CORS configuration
• Input validation
• Secure password hashing

Database Schema

Core Tables

• applications - Main application data
• application_keys - Authentication keys
• attachments - File storage (Base64)
• application_attachments - Link table
• comparison_offers - Cost comparison data
• cost_position_justifications - Justification text

Key Relationships

• Applications ↔ Keys (1:N)
• Applications ↔ Attachments (N:N)
• Applications ↔ Comparison Offers (1:N)

Scalability Considerations

Horizontal Scaling

• Stateless API design
• Database connection pooling
• Load balancer ready
• Containerized deployment

Performance Optimizations

• Database indexes on foreign keys
• Lazy loading of attachments
• Efficient PDF streaming
• Response caching headers
• Gzip compression

Development vs Production

Development Environment

• Hot reloading (frontend & backend)
• Debug logging
• Local file storage
• Relaxed CORS
• Default credentials

Production Environment

• Optimized builds
• Error tracking
• Cloud storage ready
• Strict CORS
• Secret management
• SSL/TLS encryption

Future Architecture Considerations

Potential Enhancements

1. Microservice Separation

   • PDF service
   • Authentication service
   • Notification service

2. External Storage

   • S3-compatible object storage
   • CDN for static assets

3. Caching Layer

   • Redis for session management
   • Application data caching

4. Message Queue

   • Async PDF generation
   • Email notifications

5. Monitoring

   • Application metrics
   • Performance monitoring
   • Error tracking