PDF Template Automation Engine

A web application that automatically maps data to PDF templates to generate completed PDFs.

📋 Table of Contents

Key Features
Tech Stack
Quick Start
Usage
API Documentation
Font Configuration
Project Structure

✨ Key Features

🎯 Core Features

📄 PDF Template Upload: Upload and manage A4 PDF templates
🎨 Visual Field Mapping: Drag and drop to specify data paths for template fields
⚡ Real-time Preview: Instantly check field placement
💾 Real-time Testing: Test rendering before saving
🔄 Automatic PDF Generation: Automatically generate completed PDFs from JSON data
🔌 REST API: Use via HTTP API from programs

🛠️ Editing Features

Property Editing: Real-time adjustment of position (X, Y), size (width, height), font, alignment
Field Management: Add, delete, select fields
Template Management: Individual/bulk delete support

🏗️ Tech Stack

Backend

FastAPI (0.104.1) - High-performance Python web framework
PyMuPDF (fitz) (1.23.8) - PDF information extraction and image rendering
pypdf (3.17.1) - PDF merging
Uvicorn - ASGI server

Frontend

React (18.2.0) - UI framework
Vite (5.0.8) - Fast build tool
Axios (1.6.2) - HTTP client

🚀 Quick Start

Prerequisites

Docker and Docker Compose (for local development)
AWS CLI (for deployment)
Python 3.9+ and Node.js 16+ (optional, for development without Docker)

1. Clone Repository

git clone https://github.com/CobyApp/report.git
cd report

2. Run with Docker Compose (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Access:

Frontend: http://localhost
Backend API: http://localhost:8000
API Documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

3. Run Individually (Development)

Terminal 1 - Backend:

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install packages
pip install -r requirements.txt

# Run server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

cd frontend

# Install packages
npm install

# Run development server
npm run dev

Access:

Frontend: http://localhost:3000
Backend API: http://localhost:8000

🚀 AWS Deployment

Prerequisites

AWS Account with appropriate permissions
AWS CLI installed and configured
Docker installed and running

Step 1: Setup IAM Roles (First Time Only)

# Setup IAM roles for Elastic Beanstalk
./setup-iam.sh

Step 2: Deploy to AWS

# Deploy to AWS Elastic Beanstalk (Tokyo region)
./deploy.sh

This script will:

Build Docker images for backend and frontend
Push images to AWS ECR (Elastic Container Registry)
Package the application with Dockerfile
Deploy to Elastic Beanstalk environment

Note: First deployment may take 10-15 minutes.

Step 3: Access Deployed Application

After deployment completes, get your application URL:

aws elasticbeanstalk describe-environments \
  --application-name pdf-template-engine \
  --environment-names pdf-template-prod \
  --region ap-northeast-1 \
  --query 'Environments[0].CNAME' \
  --output text

Access your application at: http://<your-cname>.elasticbeanstalk.com

📖 Usage

1. Upload Template

Access the application in your web browser (http://localhost for Docker, http://localhost:3000 for dev)
Register or login to your account
Click "Upload PDF Template" button
Select A4 PDF template file

2. Field Mapping

Click uploaded template card to enter edit mode
Drag on PDF preview to select field area
Enter data path in input popup (e.g., customer.name, items[0].price)
Add fields as needed

3. Property Editing

Click field to select
Modify in right property panel:
- Data Path: JSON path to map to field
- X, Y: Field position (PDF coordinates)
- Width, Height: Field size
- Font Size: Text size
- Alignment: Left/Center/Right

4. Test Rendering

Click "🧪 Test Rendering" button
Enter values for each field (prompt)
Completed PDF automatically downloads
Changes are reflected before saving

5. Save

Click "💾 Save" button
Template mapping information is saved to server

🔤 Font Configuration

This application supports automatic font selection based on text language:

Japanese: MS Gothic (government standard) → MS Mincho → Noto Sans JP
Korean: Malgun Gothic → Nanum Gothic → Noto Sans KR
English: Times-Roman (formal documents)

Font Installation

Quick Setup (Recommended):

# Run the automatic font installation script
./install-fonts.sh

This script will download:

Nanum Gothic (Korean)
Noto Sans JP (Japanese, if not already present)
Noto Sans KR (Korean, if not already present)

Manual Installation:

Download required fonts (see FONTS.md for direct download links)
Copy font files to backend/fonts/ directory
Restart the application

For Mac/Linux users:

The install-fonts.sh script downloads open-source fonts automatically
For MS Gothic/Mincho and Malgun Gothic, copy from Windows: C:\Windows\Fonts\

Note: The application includes Noto Sans JP and Noto Sans KR fonts by default. For Japanese government document compatibility, install MS Gothic or MS Mincho fonts. See FONTS.md for detailed instructions and download links.

📡 API Documentation

Endpoint List

Method	Path	Description
`POST`	`/api/templates`	Upload PDF template
`GET`	`/api/templates`	List templates
`GET`	`/api/templates/{id}`	Get template details
`PUT`	`/api/templates/{id}/mapping`	Save template mapping
`POST`	`/api/render/{id}`	Generate PDF (requires data)
`GET`	`/api/templates/{id}/preview`	Page preview image
`DELETE`	`/api/templates/{id}`	Delete template
`DELETE`	`/api/templates`	Delete all templates

Usage Examples

Upload Template

curl -X POST http://localhost:8000/api/templates \
  -F "file=@template.pdf"

Response:

{
  "template_id": "uuid-here",
  "filename": "template.pdf",
  "page_count": 1,
  "page_size": {"w_pt": 595.28, "h_pt": 841.89}
}

Save Template Mapping

curl -X PUT http://localhost:8000/api/templates/{template_id}/mapping \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      {
        "id": "elem1",
        "type": "text",
        "page": 1,
        "bbox": {"x": 100, "y": 100, "w": 200, "h": 20},
        "data_path": "customer.name",
        "style": {"font": "Helvetica", "size": 10, "align": "left"}
      }
    ]
  }'

Generate PDF

Generate a completed PDF by providing field data that matches your template's data paths.

Request:

curl -X POST http://localhost:8000/api/render/{template_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "address": "123 Main St"
    },
    "items": [
      {"name": "Item 1", "price": 10000, "quantity": 2},
      {"name": "Item 2", "price": 20000, "quantity": 1}
    ],
    "checked": true,
    "total": 40000,
    "date": "2024-01-17"
  }' \
  --output result.pdf

Response:

Content-Type: application/pdf
Body: Binary PDF file
Filename: rendered_{template_id}.pdf

Request Body Structure:

{
  // Field data that matches template data paths
  // Example: if template has "customer.name", provide:
  "customer": {
    "name": "John Doe"
  },
  
  // Array fields: use "items[0].price" in template
  "items": [
    {"name": "Item 1", "price": 10000}
  ],
  
  // Simple boolean fields
  "checked": true,
  
  // Optional: Override template elements for testing
  "_elements": [
    {
      "id": "elem1",
      "type": "text",
      "page": 1,
      "bbox": {"x": 100, "y": 100, "w": 200, "h": 20},
      "data_path": "customer.name"
    }
  ]
}

Error Responses:

400 Bad Request: Invalid data or template structure
```
{"detail": "Template structure error: ..."}
```
401 Unauthorized: Authentication required
```
{"detail": "Authentication required"}
```
403 Forbidden: Template does not belong to user
```
{"detail": "Access denied"}
```
404 Not Found: Template not found
```
{"detail": "Template not found"}
```

Real-time elements transmission (test rendering):

Include _elements in the request body to override template elements without saving:

curl -X POST http://localhost:8000/api/render/{template_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {"name": "John Doe"},
    "_elements": [
      {
        "id": "elem1",
        "type": "text",
        "page": 1,
        "bbox": {"x": 100, "y": 100, "w": 200, "h": 20},
        "data_path": "customer.name"
      }
    ]
  }' \
  --output result.pdf

API Documentation:

For interactive API documentation and detailed request/response schemas, visit:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

📁 Project Structure

report/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── main.py         # FastAPI app and API endpoints
│   │   └── services/
│   │       ├── pdf_service.py      # PDF processing (upload, preview)
│   │       ├── template_service.py # Template save/load
│   │       ├── render_service.py   # PDF rendering engine
│   │       └── auth_service.py    # Authentication service
│   ├── templates/          # Template JSON storage (auto-generated)
│   ├── uploads/            # Uploaded PDFs and generated PDFs (auto-generated)
│   ├── users/              # User data (auto-generated)
│   ├── fonts/              # Font files (NotoSansJP, NotoSansKR)
│   └── requirements.txt    # Python package dependencies
│
├── frontend/               # React frontend
│   ├── src/
│   │   ├── App.jsx         # Main app component
│   │   ├── components/     # React components
│   │   ├── contexts/       # React contexts (Auth)
│   │   └── i18n/           # Internationalization
│   ├── nginx.conf          # Nginx configuration
│   ├── package.json        # Node.js package dependencies
│   └── vite.config.js      # Vite configuration
│
├── .ebextensions/          # Elastic Beanstalk configuration
│   ├── 01_nginx.config     # Nginx configuration
│   └── 02_storage.config   # Storage configuration
│
├── Dockerfile              # Combined Dockerfile for production
├── docker-compose.yml      # Docker Compose configuration
├── deploy.sh               # AWS deployment script
├── setup-iam.sh            # IAM roles setup script
└── README.md               # This file

📐 Template JSON Structure

Templates are saved in JSON format:

{
  "template_id": "uuid",
  "filename": "template.pdf",
  "page_size": {
    "w_pt": 595.28,
    "h_pt": 841.89
  },
  "pages": [
    {
      "page": 1,
      "width": 595.28,
      "height": 841.89,
      "width_pt": 595.28,
      "height_pt": 841.89
    }
  ],
  "elements": [
    {
      "id": "elem_1234567890",
      "type": "text",
      "page": 1,
      "bbox": {
        "x": 100,
        "y": 200,
        "w": 200,
        "h": 20
      },
      "data_path": "customer.name",
      "style": {
        "font": "Helvetica",
        "size": 10,
        "align": "left"
      },
      "overflow": {
        "mode": "shrink_to_fit",
        "min_size": 7
      }
    }
  ],
  "created_at": "2026-01-17T..."
}

Field Descriptions

bbox: Field position and size (PDF coordinate system, point units)
- x, y: Top-left corner coordinates (stored in screen coordinates, converted during rendering)
- w, h: Width, height
data_path: JSON data path (e.g., customer.name, items[0].price)
style: Text style settings
overflow: Text overflow handling (currently supports shrink_to_fit)

✅ Supported Features

✅ Text Fields: Data path mapping, alignment, auto-shrink
✅ Checkboxes: Boolean value display
✅ Repeat Tables: List data repeat rendering
✅ Multi-page: Multiple page support
✅ Real-time Editing: Test before saving
✅ Property Editing: Real-time adjustment of position, size, style
✅ User Authentication: Login/registration for user-specific data management

🔮 Future Improvements

Image fields (signatures, stamps, QR codes)
Conditional display (if statements)
Automatic page overflow handling
Improved CJK font support
Rich text (partial bold, colors, etc.)
Data schema validation UI
Template version management

🐛 Troubleshooting

Docker Issues

# Check Docker is running
docker ps

# View container logs
docker-compose logs -f

# Restart containers
docker-compose restart

# Rebuild containers
docker-compose up -d --build

Port Already in Use

# Check ports
lsof -ti:8000  # Backend
lsof -ti:80    # Frontend (Docker)
lsof -ti:3000  # Frontend (Dev mode)

# Kill processes
kill -9 $(lsof -ti:8000)
kill -9 $(lsof -ti:80)
kill -9 $(lsof -ti:3000)

AWS Deployment Issues

# Check deployment status
aws elasticbeanstalk describe-environments \
  --application-name pdf-template-engine \
  --environment-names pdf-template-prod \
  --region ap-northeast-1

# View deployment logs
aws elasticbeanstalk request-environment-info \
  --application-name pdf-template-engine \
  --environment-name pdf-template-prod \
  --info-type tail \
  --region ap-northeast-1

Package Installation Errors

Backend:

# Check virtual environment
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Frontend:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

🤝 Contributing

Issues and pull requests are welcome!

📄 License

MIT License

Project Link: https://github.com/CobyApp/report

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.ebextensions		.ebextensions
backend		backend
frontend		frontend
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
FONTS.md		FONTS.md
FONT_INSTALL_GUIDE.md		FONT_INSTALL_GUIDE.md
README.md		README.md
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml
install-fonts.sh		install-fonts.sh
setup-iam.sh		setup-iam.sh

CobyApp/report

Folders and files

Latest commit

History

Repository files navigation

PDF Template Automation Engine

📋 Table of Contents

✨ Key Features

🎯 Core Features

🛠️ Editing Features

🏗️ Tech Stack

Backend

Frontend

🚀 Quick Start

Prerequisites

1. Clone Repository

2. Run with Docker Compose (Recommended)

3. Run Individually (Development)

🚀 AWS Deployment

Prerequisites

Step 1: Setup IAM Roles (First Time Only)

Step 2: Deploy to AWS

Step 3: Access Deployed Application

📖 Usage

1. Upload Template

2. Field Mapping

3. Property Editing

4. Test Rendering

5. Save

🔤 Font Configuration

Font Installation

📡 API Documentation

Endpoint List

Usage Examples

Upload Template

Save Template Mapping

Generate PDF

📁 Project Structure

📐 Template JSON Structure

Field Descriptions

✅ Supported Features

🔮 Future Improvements

🐛 Troubleshooting

Docker Issues

Port Already in Use

AWS Deployment Issues

Package Installation Errors

🤝 Contributing

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages