High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Rosy Tax Processor is an AI-powered system designed to automate the preparation of personal tax returns by processing documents such as W-2s and 1099s. The architecture follows a modular pipeline approach that integrates document ingestion, field extraction, tax calculation, and automated PDF form-filling into a cohesive workflow. Sources: README.md:3-8
The system is structured as a client-server application. A Flask-based backend orchestrates the core logic, while a JavaScript frontend provides a user interface for document uploading, data review, and finalization of Form 1040 documents. Sources: backend.py:6-12, frontend/app.js:1-5
System Component Overview
The architecture is divided into several discrete modules, each responsible for a specific stage of the tax processing lifecycle.
| Component | Description | Key Files |
|---|---|---|
| API Backend | Flask server handling routing, file uploads, and pipeline orchestration. | backend.py, security.py |
| Processing Pipeline | The core engine that sequences ingestion, classification, and extraction. | pipeline.py |
| Tax Engine | Progressive tax calculator using filing status and tax brackets. | taxcalc.py |
| Form Generator | Handles PDF generation via ReportLab or AcroForm filling via pdfrw. | forms.py, utils/auto_mapper.py |
| Frontend | Web-based UI for user interaction and document review. | frontend/app.js, frontend/index.html |
Sources: README.md:21-40, backend.py:10-15
Data Flow and Orchestration
The system utilizes a central orchestration function, run_pipeline_on_paths, to manage the transition of data between modules. The workflow begins with raw document ingestion and ends with a generated tax form. Sources: pipeline.py:42-45
This diagram illustrates the sequential flow of data from the initial user upload to the final PDF generation.
Sources: pipeline.py:42-88, backend.py:51-100
Processing Pipeline Stages
- Ingestion & Classification: Documents (PDF, TXT, PNG, JPG) are converted to text. The system detects the document type (e.g., W-2 vs 1099) with an associated confidence score. Sources: pipeline.py:17-25, security.py:10
- Field Extraction: Regex or heuristic-based logic extracts specific tax fields like wages, withholding, SSN, and EIN. Sources: pipeline.py:22, README.md:22
- Aggregation: Data from multiple files is consolidated. For example, wages from multiple W-2s are summed to calculate the total income. Sources: pipeline.py:53-76
- Tax Computation: The engine applies standard deductions and progressive tax brackets based on the user's filing status (Single or Married). Sources: taxcalc.py:65-85
PDF Generation and Field Mapping
A critical feature of the architecture is the ability to map extracted data onto existing PDF templates (AcroForms). The system uses a two-tier mapping strategy. Sources: forms.py:140-165
Smart Field Mapping
When exact field names are not known, the system employs an auto_mapper utility. It attempts to use semantic embeddings (via sentence-transformers) to find the best match between parsed data and PDF field labels. If ML dependencies are missing, it falls back to string similarity algorithms. Sources: utils/auto_mapper.py:14-25, utils/auto_mapper.py:44-55
PDF Filling Logic
The forms.py module manages the creation of the final document:
- AcroForm Filling: Uses
pdfrwto inject values into fillable PDF fields. Sources: forms.py:104-120 - ReportLab Fallback: If no template is found, it generates a simple PDF draft from scratch. Sources: forms.py:67-75
Sequence of events during the PDF finalization stage.
Sources: forms.py:140-195
Backend API Specification
The Flask backend exposes endpoints for document processing and user-driven finalization. Sources: backend.py:15-20
| Endpoint | Method | Purpose | Parameters |
|---|---|---|---|
/upload | POST | Processes uploaded documents and returns extracted data. | files, filing_status, withholding |
/finalize | POST | Accepts edited data from the user and generates the final PDF. | per_file (JSON), filing_status |
/download | GET | Serves the generated PDF file. | path |
Sources: backend.py:51, backend.py:103, backend.py:38
Security and Privacy
The architecture prioritizes local processing and data protection. Key security features include:
- PII Masking: Sensitive information like SSNs (e.g.,
123-45-6789) is masked in API responses to the frontend (e.g.,XXX-XX-6789). Sources: security.py:32-37 - File Validation: The system enforces a 5MB limit per file and restricts uploads to specific extensions (PDF, TXT, PNG, JPG). Sources: security.py:10-11
- Sanitization: Filenames are sanitized to prevent path traversal attacks before being stored in temporary directories. Sources: security.py:15-22
Summary
The Rosy Tax Processor architecture provides an automated pipeline for tax document transformation. By combining heuristic extraction with semantic field mapping and a progressive tax engine, the system bridge the gap between raw financial documents and formatted tax filings. Its modular design allows for independent scaling or replacement of the extraction and calculation components. Sources: README.md:143-150