🥖 Pan Tributario

Automated Tax Form Processing for Ecuador

Transforming 3-4 hours of manual work into 10 seconds

Live Demo · Report Bug · Request Feature

📋 Table of Contents

About
Features
Tech Stack
Screenshots
Getting Started
Architecture
API Documentation
Deployment
Roadmap
Contributing
License
Contact

🎯 About

Pan Tributario is a full-stack SaaS application that automates the extraction and processing of Ecuadorian tax forms (SRI Forms 103 & 104). Built to solve a real problem faced by accountants and businesses, it reduces manual data entry from 3-4 hours per client to just 10 seconds.

The Problem

Ecuadorian accountants manually extract financial data from PDF tax forms:

Form 103 (Retenciones): 10+ fields per document
Form 104 (IVA): 130+ fields across 7 sections
Time required: 3-4 hours per client
Monthly workload: 150-200 hours for 50 clients
Error rate: ~5% due to manual entry

The Solution

Automated PDF processing with:

⚡ 1,440x faster processing (3-4 hours → 10 seconds)
✅ Zero errors through automated extraction
📊 Professional reports (Excel & PDF exports)
👥 Multi-client management with yearly summaries
🔐 Complete data isolation between users

✨ Features

Core Functionality

📤 Drag-and-drop PDF upload with bulk processing
🔍 Automatic form detection (103 vs 104)
📊 Intelligent field extraction using regex patterns
💾 Client management organized by company and year
📈 Yearly accumulations for tax reporting
📄 Professional exports (Excel with formulas, branded PDFs)

User Experience

🎨 Dark mode with proper contrast ratios
📱 Mobile responsive design
🚀 Real-time processing with progress indicators
🎯 Guest mode (5 free documents, no signup)
♾️ Unlimited access for registered users

Security & Authentication

🔐 Google OAuth 2.0 integration
🔒 Bcrypt password hashing
🤖 reCAPTCHA v3 bot protection
🛡️ Multi-tenant architecture with complete user isolation
🍪 Secure session management

Technical Features

⚡ Async processing for optimal performance
💾 10 database tables with proper relationships
🔄 35+ API endpoints (RESTful)
📊 Analytics dashboard for admins
🌐 CDN integration (Cloudflare) for 70%+ cache rate

🛠️ Tech Stack

Frontend

Backend

DevOps & Tools

📸 Screenshots

Landing Page

CLients Interface

Form 103 Display

Yearly Summary

Light Mode

🚀 Getting Started

Prerequisites

Node.js 18+ and npm
Python 3.11+
PostgreSQL 15+
Docker (optional)

Installation

1. Clone the repository

git clone https://github.com/CapBraco/tax_form_processor.git
cd tax_form_processor

2. Backend Setup

cd backend

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

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env
# Edit .env with your database credentials

# Run migrations
alembic upgrade head

# Start server
uvicorn main:app --reload

Backend will run at http://localhost:8000

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Create .env.local file
cp .env.example .env.local
# Edit .env.local with your backend URL

# Start development server
npm run dev

Frontend will run at http://localhost:3000

Environment Variables

Backend (.env)

DATABASE_URL=postgresql://user:password@localhost:5432/taxforms
SECRET_KEY=your-secret-key-min-32-characters
FRONTEND_URL=http://localhost:3000
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-secret
RECAPTCHA_SECRET_KEY=your-recaptcha-secret

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your-recaptcha-site-key

Docker Setup (Alternative)

# Build and run with docker-compose
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend: http://localhost:8000

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────┐
│                    CLIENT LAYER                          │
│  (Next.js Frontend - React Components & TypeScript)     │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ HTTPS/REST API
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    API LAYER                             │
│    (FastAPI - Async Python with Pydantic validation)    │
│                                                          │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐            │
│  │   Auth   │  │  Upload   │  │ Clients  │            │
│  │  Routes  │  │  Routes   │  │  Routes  │            │
│  └──────────┘  └───────────┘  └──────────┘            │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ SQLAlchemy ORM
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  DATABASE LAYER                          │
│         (PostgreSQL - 10 Tables, JSONB fields)          │
│                                                          │
│  users • documents • form_103_data • form_104_data      │
│  guest_sessions • temporary_files • analytics           │
└─────────────────────────────────────────────────────────┘

Data Flow: PDF Upload & Processing

1. User uploads PDF → Frontend validates file
2. API receives file → Saves to temp storage
3. pdfplumber extracts text → Regex patterns parse fields
4. Data saved to database → Async SQLAlchemy commit
5. Frontend polls status → Real-time updates
6. Success response → Display extracted data

Database Schema

Key Tables:

users - Authentication and profiles
documents - Metadata for uploaded PDFs
form_103_data - Extracted data from Form 103
form_104_data - Extracted data from Form 104 (130 fields)
guest_sessions - Temporary sessions with document limits

📚 API Documentation

Interactive API documentation available at:

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

Key Endpoints

Authentication

POST   /api/auth/register          # Create new account
POST   /api/auth/login             # Login with credentials
POST   /api/auth/google            # Google OAuth login
POST   /api/auth/logout            # Logout
GET    /api/auth/me                # Get current user

Documents

POST   /api/upload/bulk            # Upload multiple PDFs
GET    /api/documents              # List user documents
GET    /api/documents/{id}         # Get document details
DELETE /api/documents/{id}         # Delete document

Forms

GET    /api/forms-data/103/{id}    # Get Form 103 data
GET    /api/forms-data/104/{id}    # Get Form 104 data

Clients

GET    /api/clientes               # List user clients
GET    /api/clientes/{name}        # Get client details
POST   /api/clientes/export        # Export to Excel/PDF

🚀 Deployment

Railway Deployment (Current)

Backend Service
- Build: Dockerfile in backend/
- Start: uvicorn main:app --host 0.0.0.0 --port $PORT
- Environment: Production variables from Railway
Frontend Service
- Build: npm run build
- Start: npm run start
- Environment: Production variables from Railway
PostgreSQL Database
- Managed by Railway
- Automatic backups
- Connection string in DATABASE_URL

Custom Domain Setup

Point DNS to Railway (CNAME)
Configure Cloudflare for CDN
Enable SSL/TLS (Full strict mode)
Set up page rules for caching

🗺️ Roadmap

Q1 2025

Form 101 support (Impuesto a la Renta)
Form 106 support (ATS)
Email notifications
Bulk document deletion

Q2 2026

Mobile app (React Native)
API for third-party integrations
Advanced analytics dashboard
Scheduled reports (weekly/monthly)

Q3 2026

Multi-language support (English)
WhatsApp notifications
Collaborative features (team accounts)

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Contact

Bryan A Paucar - @devbraco

Project Link: https://github.com/CapBraco/tax_form_processor

Live Demo: https://tax.capbraco.com

🙏 Acknowledgments

Inspired by real-world accounting workflows in Ecuador
Thanks to my father for inspiring me to build this app
Built with modern web technologies and best practices
Special thanks to the FastAPI and Next.js communities

Made with ❤️ by Bryan A Paucar

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
backend		backend
docs/images		docs/images
frontend		frontend
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
backup.sql		backup.sql
cookies.txt		cookies.txt
docker-compose.yml		docker-compose.yml
railway.json		railway.json

CapBraco/tax_form_processor

Folders and files

Latest commit

History

Repository files navigation