Frontend Logic & State
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Frontend Logic & State" module manages the user interface, document upload process, and data reconciliation for the Rosy Tax Processor. It serves as the bridge between the end-user and the Processing Pipeline, enabling users to upload tax documents (W-2, 1099), review AI-extracted fields, and finalize calculations to generate a 1040 PDF.
The frontend is implemented as a single-page application (SPA) style interface using vanilla JavaScript, HTML5, and CSS. It maintains local state for parsed document data, allowing for real-time edits before final submission to the backend.
Sources: README.md:10-25, frontend/app.js:1-10
Core Architecture and Data Flow
The frontend operates through a three-stage lifecycle: Upload & Ingestion, Review & Edit, and Finalization. It uses FormData for multi-file binary uploads and fetch for asynchronous communication with the Flask backend.
User Interaction Flow
The following diagram illustrates the lifecycle of a document from selection to PDF download:
The UI maintains state by storing the JSON response from the server and dynamically regenerating the "Aggregated Preview" whenever a user modifies a specific field in the review section.
Sources: frontend/app.js:1-100, backend.py:48-125
State Management and Document Review
The frontend handles a complex data structure returned by the /upload endpoint. This structure includes per-file parsing results and an initial aggregation of tax data.
Key Data Structures
The frontend processes a JSON object containing the following primary components:
| Field | Type | Description |
|---|---|---|
doc_type | String | Legacy detected document type for the combined batch. |
per_file | Array | Objects containing path, fields, and confidence for each uploaded file. |
aggregated_fields | Object | Summed wages and withholding across all documents. |
tax_estimate | Object | Calculated AGI, taxable income, and tax due/refund. |
Sources: frontend/app.js:41-55, pipeline.py:76-88
Local State Synchronization
When a user modifies a field in the "Per-file parsing" section, the renderResult function attaches event listeners to "Save changes" buttons. These listeners update the local j.per_file object and trigger a re-render of the aggregated view.
saveBtn.addEventListener('click', (ev) => {
const els = form.querySelectorAll('input');
els.forEach(e => { pf.fields[e.name] = e.value; });
statusEl.textContent = 'Updated fields for ' + pf.path;
renderAggregated(j);
});
Sources: frontend/app.js:77-85
Backend Communication & API Interaction
The frontend interacts with two primary API endpoints to manage the document lifecycle.
Endpoint Specifications
| Endpoint | Method | Payload | Response |
|---|---|---|---|
/upload | POST | FormData (files, status, withholding) | JSON with parsed field data |
/finalize | POST | JSON (per_file array, filing_status) | PDF Blob (Binary) |
Finalization Sequence
The finalization process sends the potentially edited field data back to the server to ensure the generated PDF reflects user corrections.
DOM Elements and UI Components
The user interface is defined in index.html and manipulated via app.js. Key components include:
- Upload Form (
upload-form): Captures filing status (Single/Married), manual withholding overrides, and multiple files. - Status Element (
status): Provides ARIA-live polite updates on processing progress (e.g., "Preparing upload...", "Processing complete"). - Result Area (
result): A container where the review forms and aggregated previews are dynamically injected. - Aggregated Area (
aggregated-area): A specific sub-section for final tax previews and the finalization trigger.
Sources: frontend/index.html:14-30, frontend/app.js:41-50, frontend/static.css:1-10
Conclusion
The frontend of the Tax Processor is designed for high transparency and user control. By implementing a "Review & Edit" loop, it mitigates potential AI extraction errors from the backend pipeline. The logic ensures that any manual corrections made by the user are preserved in the final state sent to the /finalize endpoint, resulting in an accurate Form 1040 generation.