API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Rosy Tax Processor provides a web-based API built with Flask to handle tax document ingestion, automated field extraction, and Form 1040 generation. The API serves as the bridge between the frontend user interface and the backend processing pipeline, which coordinates document classification, tax estimation, and PDF form filling.
This reference details the available endpoints, expected data structures, and the internal processing flow triggered by API requests.
Sources: backend.py:1-12, README.md:16-32
Core Endpoints
POST /upload
Processes one or more uploaded tax documents (W-2, 1099, etc.) through the full extraction and calculation pipeline.
| Parameter | Type | Description |
|---|---|---|
files | file[] | Multipart form-data containing one or more PDF, image, or text files. |
filing_status | string | User-selected status: "single" or "married" (default: "single"). |
withholding | number | Optional manual withholding amount to override extracted values. |
Success Response: Returns a JSON object containing aggregated tax data and per-file parsing details. Sensitive PII like SSNs are masked in the response.
Processing Logic:
- Sanitizes filenames and validates file extensions against
ALLOWED_EXT. - Checks file sizes against
MAX_UPLOAD_BYTES(5 MB). - Invokes
run_pipeline_on_pathsto perform OCR, classification, and field extraction. - Aggregates financial totals (wages, withholding) and computes tax estimates.
- Cleans up temporary storage before returning results.
Sources: backend.py:46-95, security.py:10-12
POST /finalize
Accepts edited field data from the frontend to generate the final Form 1040 PDF.
| Field | Type | Description |
|---|---|---|
per_file | array | List of objects containing edited field values for each document. |
filing_status | string | The filing status to apply to the final calculation. |
Success Response: Streams a generated PDF file (draft_1040.pdf) as an attachment.
Sources: backend.py:98-138
GET /download
Helper endpoint used during the demo to retrieve generated files from temporary storage.
| Query Param | Type | Description |
|---|---|---|
path | string | The full file path to the generated document. |
Sources: backend.py:33-44
Data Flow Architecture
The API initiates a multi-stage pipeline that transitions data from raw files to structured tax forms.
The diagram above illustrates the request lifecycle from the initial upload to the return of sanitized results.
Sources: pipeline.py:11-30, backend.py:46-95
Internal Pipeline Logic
Tax Calculation Engine
The taxcalc.py module computes federal estimates based on progressive tax brackets and standard deductions.
| Variable | Description | Source |
|---|---|---|
STANDARD_DEDUCTIONS | Single: 13,850; Married: 27,700 | taxcalc.py:11-14 |
agi | Sum of all extracted 'wages' and 'amount' fields. | taxcalc.py:76-80 |
taxable_income | max(0, agi - deductions) | taxcalc.py:83 |
tax_due | gross_tax - withholding | taxcalc.py:89 |
PDF Form Generation
The system attempts to fill a standard 1040 template if available, otherwise it generates a dynamic PDF using ReportLab.
The PDF generation process uses semantic mapping to align extracted fields (e.g., "wages") with PDF-specific field names (e.g., "(Wages)").
Sources: forms.py:117-178, utils/auto_mapper.py:39-65
Security and Sanitization
The API implements several security layers to protect the host system and user data.
- Filename Sanitization: The
sanitize_filenamefunction restricts names to alphanumerics, dots, dashes, and underscores, limiting length to 200 characters. - PII Masking: Before returning JSON results to the client, the
mask_pii_in_resultfunction recursively searches for keys associated with sensitive data and applies regex patterns to mask Social Security Numbers (e.g.,XXX-XX-6789). - Path Validation: The
/downloadendpoint verifies that requested paths contain the application's unique temporary prefix (rosy_upload_) to prevent path traversal.
Sources: security.py:15-52, backend.py:40-42
Summary
The Rosy Tax Processor API provides a streamlined interface for automated tax preparation. By coordinating complex parsing, semantic field mapping, and progressive tax calculations, it transforms raw document uploads into structured, reviewable tax data and finalized PDF forms. The architecture emphasizes security through strict input validation and PII masking, ensuring sensitive financial information is handled safely throughout the processing lifecycle.