Tax Practice AI Backbone System
Requirements Specification Document
Version: 1.0 Draft
Date: December 22, 2025
Status: Pending Client Input
Table of Contents
- Executive Summary
- Follow-Up Questions
- Functional Requirements
- Compliance and Regulatory Requirements
- Security Requirements
- Infrastructure and Scalability
- Integration Requirements
- User Experience Requirements
- AI Capabilities
- Implementation Plan
- Appendices
| Document |
Purpose |
| DATA_MODEL.md |
Logical data model: 35+ entities with full attribute specifications, ER diagrams, and enum definitions |
| PROCESS_FLOWS.md |
State machines (Tax Return, Document, E-Filing, Identity Verification) and process flow diagrams |
| ARCHITECTURE.md |
System architecture: services, database, integrations, infrastructure |
| bookkeeping_requirements.md |
Separate bookkeeping module requirements (future phase) |
1. Executive Summary
1.1 Purpose
This document defines the requirements for an AI-powered backbone system designed to support tax preparation workflows for small to mid-size accounting firms. The system will scale from a small practice (current staff of 2) to support growth over time.
1.2 Scope
The system encompasses the complete tax preparation lifecycle:
1) Client intake and identity verification
2) Document collection and AI-powered extraction
3) Preliminary AI analysis with human review
4) Accountant review with AI assistance
5) EA/CPA final review and approval
6) Client delivery via Google Workspace signatures
7) E-filing and status monitoring
8) Estimated tax tracking and year-round client support
9) Client data portability and export
Client Data Export: When clients leave the firm, the system shall support generating a complete export package containing all documents, return copies, communication history, and an AI-generated account summary. This may be offered as a fee-based service to cover administrative costs, subject to applicable privacy law requirements.
Bookkeeping Module: Monthly bookkeeping services (bank statement processing, transaction categorization, QuickBooks integration) are planned as a separate phase. Requirements are tracked in bookkeeping_requirements.md to allow independent development and prioritization. The bookkeeping module shares infrastructure (client portal, document upload, AI, database) with the tax preparation system.
1.3 Key Design Principles
1) AI-Assistive, Human-Controlled — AI provides analysis and recommendations; licensed professionals make all final decisions
2) Compliance-First — IRS Circular 230, WISP, and state requirements are foundational, not afterthoughts
3) Accessibility-Conscious — Client base includes senior citizens; all interfaces must accommodate diverse technical abilities
4) Scalable Architecture — System must grow from hundreds to thousands of returns without re-architecture
5) Audit-Ready — Complete activity logging and document versioning from day one
1.4 Assumptions
Technical Assumptions:
1) Integration with existing tax preparation software via API (specific software TBD per follow-up questions)
2) Third-party e-filing transmitter (not direct IRS MeF integration)
3) Google Workspace as the firm's existing collaboration platform
4) AWS as primary cloud provider with multi-region deployment
5) Google Workspace for client document signing (e-signatures)
Operational Assumptions:
6) Initial deployment targeting individual returns (1040) with business entity support in future phases
7) Single-preparer workflow initially; multi-preparer queuing and load balancing in v2
8) Clients have email access; paper-only clients handled as documented exceptions
9) English language only for initial release
10) US federal and state returns only; no international tax support initially
Client Interaction Assumptions:
11) Clients will primarily interact via web portal and email
12) Phone support available during business hours for clients who prefer voice communication
13) Senior citizen accommodations are a priority given client demographics
2. Follow-Up Questions
The following questions must be answered before implementation planning can proceed:
2.1 Tax Software
Question: What tax preparation software does the firm currently use?
Answer: UltraTax CS (Thomson Reuters)
| Aspect |
Details |
| Software |
UltraTax CS |
| Vendor |
Thomson Reuters |
| API Available |
No public API |
| Integration Path |
Via SurePrep CS Connect (native integration) |
Impact: UltraTax CS has no public API. Integration must go through SurePrep, which has both an API and native CS Connect integration with UltraTax. Direct data push to UltraTax is not possible without SurePrep as intermediary.
2.2 Volume Projections
Question: What are the projected return volumes?
Answer: Approximately 1,000 returns per year currently, with 30% growth projected within two years based on current trajectory.
| Timeframe |
Returns per Year |
Notes |
| Current |
~1,000 |
Baseline |
| Year 2 |
~1,300 |
30% growth (current trajectory) |
| Year 3+ |
TBD |
With AI automation, growth could accelerate significantly |
Impact: At 1,000-1,300 returns/year, the system falls in the "Small to Medium" tier. AI-powered automation enables scaling without proportional staff increases, potentially supporting faster growth than current trajectory.
2.3 Entity Type Mix
Question: What is the approximate breakdown of return types?
Answer: Mix varies from simple individual (1040) to complex business returns. Exact percentages TBD.
| Return Type |
Form |
Percentage |
| Individual |
1040 |
TBD |
| S-Corporation |
1120S |
TBD |
| Partnership |
1065 |
TBD |
| C-Corporation |
1120 |
TBD |
| Trust/Estate |
1041 |
TBD |
| Nonprofit |
990 |
TBD |
Note: The firm handles the full spectrum from simple individual returns to complex business entities. This requires AI skills for all major return types from initial release.
Impact: Full-spectrum practice requires broader AI skill development. System must handle varying complexity levels and route appropriately based on return type.
2.4 State Coverage
Questions:
1) Primary states served: _____
2) Need all 50 states capability? Yes / No
Impact: Affects state-specific skills development, e-filing integrations, and compliance requirements.
2.5 Existing Software Stack
Question: What software does the firm currently use for document management and tax preparation workflow?
Answer: The firm uses an integrated Thomson Reuters ecosystem plus SmartVault.
| Function |
Software |
Vendor |
API Available |
V1 Strategy |
| Client Portal |
SmartVault |
SmartVault Inc. |
Yes (REST API) |
Integrate |
| Document Processing |
SurePrep (1040SCAN, TaxCaddy, SPbinder) |
Thomson Reuters |
Yes (REST API) |
Integrate |
| Tax Software |
UltraTax CS |
Thomson Reuters |
No |
Via SurePrep |
V1 Integration Strategy: Integrate with existing tools rather than replace. SmartVault remains the client-facing document portal. SurePrep continues to handle OCR/extraction and UltraTax data population. Our system adds AI-powered analysis, workflow orchestration, client communications, and new capabilities (bookkeeping, estimated tax tracking).
Future Consideration: SurePrep replacement is possible but requires solving the UltraTax integration problem (no API). Evaluate post-V1 based on extraction quality needs.
3. Functional Requirements
3.1 Pre-Engagement
3.1.1 Conflict of Interest Check
| ID |
Requirement |
Priority |
| PRE-001 |
System shall maintain a database of current and former clients with associated entities |
Must Have |
| PRE-002 |
System shall automatically check new client against existing client relationships |
Must Have |
| PRE-003 |
System shall flag potential conflicts for human review before engagement |
Must Have |
| PRE-004 |
System shall log all conflict check results for audit purposes |
Must Have |
3.1.2 Engagement Letter Generation
| ID |
Requirement |
Priority |
| PRE-010 |
System shall generate engagement letters from approved templates |
Must Have |
| PRE-011 |
System shall pre-populate engagement letters with client information |
Must Have |
| PRE-012 |
System shall route engagement letters through Google Workspace for signature |
Must Have |
| PRE-013 |
System shall not proceed with tax work until engagement letter is signed |
Must Have |
| PRE-014 |
System shall store signed engagement letters with client record |
Must Have |
| ID |
Requirement |
Priority |
| PRE-020 |
System shall generate Form 7216 consent when tax return information will be disclosed or used |
Must Have |
| PRE-021 |
System shall track consent expiration and prompt for renewal |
Should Have |
| PRE-022 |
System shall prevent disclosure of return information without valid consent on file |
Must Have |
3.2 Client Intake and Onboarding
3.2.1 Client Registration
| ID |
Requirement |
Priority |
| INT-001 |
System shall support registration for new clients via web portal |
Must Have |
| INT-002 |
System shall support returning client authentication with reduced friction |
Must Have |
| INT-003 |
System shall assign unique account numbers to each client |
Must Have |
| INT-004 |
System shall capture and validate contact information (email, phone, address) |
Must Have |
| INT-005 |
System shall support multiple contacts per household/entity |
Should Have |
3.2.2 Identity Verification (Tiered)
📋 Technical Reference: For the complete Identity Verification state machine (15 states across 3 tiers), see PROCESS_FLOWS.md.
| ID |
Requirement |
Priority |
| INT-010 |
System shall implement Tier 1 verification for returning clients (Name + SSN-4 + DOB + Prior Year AGI) |
Must Have |
| INT-011 |
System shall provide magic link email verification as Tier 1 fallback |
Must Have |
| INT-012 |
System shall implement Tier 2 verification for new clients (email + phone + government ID) |
Must Have |
| INT-013 |
System shall integrate with identity verification provider (Persona or equivalent) for ID document analysis |
Must Have |
| INT-014 |
System shall support voice call as alternative to SMS for phone verification |
Must Have |
| INT-015 |
System shall implement Tier 3 verification (Google Meet video call) for high-risk situations |
Must Have |
| INT-016 |
System shall offer in-person verification option for clients who prefer it |
Should Have |
| INT-017 |
System shall offer notarized affidavit option for Tier 3 verification |
Should Have |
Tier 3 Triggers:
1) New client with refund greater than $5,000 to new bank account
2) Identity verification score between 70-89%
3) Fraud indicators present
4) Client request
3.2.3 Prior Return Retrieval
| ID |
Requirement |
Priority |
| INT-020 |
System shall retrieve prior year returns from firm's document store for returning clients |
Must Have |
| INT-021 |
System shall accept client-uploaded prior year returns for new clients |
Must Have |
| INT-022 |
System shall extract key data points from prior returns for comparison |
Must Have |
| INT-023 |
System shall flag significant changes from prior year for preparer attention |
Should Have |
3.2.4 Existing Client Portal Activation
| ID |
Requirement |
Priority |
| INT-030 |
System shall allow existing clients (staff-created) to activate portal access without creating duplicate account |
Must Have |
| INT-031 |
System shall link portal activation to existing client record using identity verification |
Must Have |
| INT-032 |
System shall preserve existing account number during portal activation |
Must Have |
| INT-033 |
System shall support staff sending portal invitation emails to existing clients |
Should Have |
3.2.5 Staff Client Management
| ID |
Requirement |
Priority |
| INT-040 |
System shall allow authorized staff to create client records via admin interface |
Must Have |
| INT-041 |
System shall generate account number for staff-created clients |
Must Have |
| INT-042 |
System shall mark staff-created clients as ACTIVE (skip PENDING_VERIFICATION) |
Must Have |
| INT-043 |
System shall log staff member who created client for audit |
Must Have |
| INT-044 |
System shall support staff entering partial client information (minimum: name + email OR phone) |
Should Have |
| INT-045 |
System shall allow staff to optionally send portal invitation to client at creation |
Should Have |
3.3 Document Management
📋 Technical Reference: For the complete Document lifecycle state machine (12 states from upload through verification), see PROCESS_FLOWS.md.
3.3.1 Document Upload
| ID |
Requirement |
Priority |
| DOC-001 |
System shall accept document uploads via web portal |
Must Have |
| DOC-002 |
System shall accept documents via secure email (with account number and tax year identifier) |
Must Have |
| DOC-003 |
System shall support PDF, JPEG, PNG, HEIC image formats |
Must Have |
| DOC-003a |
System shall support DOCX (Word) documents |
Must Have |
| DOC-003b |
System shall support XLSX/CSV spreadsheets (expense logs, mileage, etc.) |
Must Have |
| DOC-003c |
System shall support email formats (MSG/EML) for forwarded documents |
Should Have |
| DOC-004 |
System shall support batch upload of multiple documents |
Must Have |
| DOC-005 |
System shall generate confirmation receipt for each upload |
Should Have |
| DOC-006 |
System shall scan uploads for malware before processing |
Must Have |
3.3.2 Document Classification and Extraction
| ID |
Requirement |
Priority |
| DOC-010 |
System shall automatically classify uploaded documents by type (W-2, 1099, 1098, etc.) |
Must Have |
| DOC-011 |
System shall extract structured data from documents using AI/OCR |
Must Have |
| DOC-012 |
System shall flag low-confidence extractions for human review |
Must Have |
| DOC-013 |
System shall store extracted data in structured format (JSON/database) |
Must Have |
| DOC-014 |
System shall maintain link between extracted data and source document |
Must Have |
| DOC-015 |
System shall support manual correction of extracted data |
Must Have |
3.3.3 Document Tracking
| ID |
Requirement |
Priority |
| DOC-020 |
System shall maintain checklist of expected documents based on prior year |
Must Have |
| DOC-021 |
System shall identify missing documents and notify client |
Must Have |
| DOC-022 |
System shall track document receipt dates |
Must Have |
| DOC-023 |
System shall support preparer adding notes to documents |
Should Have |
3.3.4 Staff Document Operations
| ID |
Requirement |
Priority |
| DOC-030 |
System shall allow staff to upload documents on behalf of clients |
Must Have |
| DOC-031 |
System shall support staff uploading entire folder of documents for a client |
Must Have |
| DOC-032 |
System shall auto-classify staff-uploaded documents by filename patterns |
Must Have |
| DOC-033 |
System shall assign tax year to staff uploads (default current, selectable) |
Must Have |
| DOC-034 |
System shall log uploading staff member for audit |
Must Have |
| DOC-035 |
System shall support drag-and-drop folder upload in admin UI |
Should Have |
| DOC-036 |
System shall generate upload summary showing classified document counts |
Should Have |
| DOC-037 |
System shall flag unclassified documents for manual review |
Should Have |
Use Cases:
- Walk-in client with box of receipts (staff scans to folder, uploads folder)
- Mailed documents (staff scans, uploads to client record)
- Documents received via fax or non-portal email
- Prior year documents from legacy system
3.4 Preliminary Analysis
3.4.1 AI-Powered Review
| ID |
Requirement |
Priority |
| ANA-001 |
System shall perform preliminary analysis of all submitted documents |
Must Have |
| ANA-002 |
System shall compare current year data to prior year and flag significant changes |
Must Have |
| ANA-003 |
System shall identify potential deductions or credits based on submitted information |
Should Have |
| ANA-004 |
System shall generate questions for client clarification |
Must Have |
| ANA-005 |
System shall identify inconsistencies or potential issues |
Must Have |
| ANA-006 |
System shall prioritize issues by materiality |
Should Have |
3.4.2 Client Communication
| ID |
Requirement |
Priority |
| ANA-010 |
System shall generate client questions via secure portal messaging |
Must Have |
| ANA-011 |
System shall send email notifications when questions are posted |
Must Have |
| ANA-012 |
System shall include account number and tax year in all communications |
Must Have |
| ANA-013 |
System shall track question/response history |
Must Have |
| ANA-014 |
System shall escalate unanswered questions after configurable time period |
Should Have |
3.4.3 Proactive Client Notifications
| ID |
Requirement |
Priority |
| COM-001 |
System shall send confirmation upon document receipt |
Must Have |
| COM-002 |
System shall generate missing document checklist based on prior year and current submissions |
Must Have |
| COM-003 |
System shall send automated follow-up reminders at configurable intervals (7, 14, 21 days) |
Should Have |
| COM-004 |
System shall notify client of return status changes |
Must Have |
| COM-005 |
System shall support client preference for communication channel (email, SMS, both) |
Should Have |
| COM-006 |
All automated messages shall include option to contact a human |
Must Have |
3.5 Tax Preparation Workflow
3.5.1 Return Status Management
📋 Technical Reference: For the complete state machine with all transitions, triggers, and guard conditions, see PROCESS_FLOWS.md.
| ID |
Requirement |
Priority |
| WFL-001 |
System shall maintain return status through defined workflow states |
Must Have |
| WFL-002 |
System shall support assignment of returns to preparers |
Must Have |
| WFL-003 |
System shall support reassignment of returns |
Must Have |
| WFL-004 |
System shall track time spent on each return |
Should Have |
| WFL-005 |
System shall provide dashboard view of all returns by status |
Must Have |
| WFL-006 |
System shall track completion percentage per return based on workflow milestones |
Should Have |
| WFL-007 |
System shall provide operator dashboard with aggregate progress metrics |
Should Have |
| WFL-008 |
System shall track cycle time by workflow state for process improvement |
Should Have |
Workflow States:
1) Intake — Client registered, awaiting documents
2) Documents Pending — Partial documents received, awaiting completion
3) Ready for Prep — All documents received, queued for AI analysis
4) AI Analysis — System performing automated extraction, comparison, and preliminary review
5) In Prep — Human preparer reviewing AI output, making corrections, applying judgment
6) Pending Client Response — Questions sent to client
7) Ready for Review — Prep complete, awaiting reviewer
8) In Review — Reviewer examining return
9) Revisions Needed — Reviewer identified issues
10) Approved — Ready for client delivery
11) Pending Signature — Awaiting client e-file authorization
12) Ready to File — Authorized, ready for transmission
13) Filed — Transmitted to IRS/state
14) Accepted — IRS/state acknowledged acceptance
15) Rejected — IRS/state rejected, needs correction
16) Complete — Return accepted, all deliverables provided
17) Needs Review — Exception state for items requiring human attention (catch-all)
Note: The "In Prep" state always involves a human preparer with valid PTIN (Circular 230 requirement). AI performs preliminary work in the "AI Analysis" state; human judgment is applied in "In Prep."
Progress Percentage Mapping:
| State |
Approximate % Complete |
| Intake |
5% |
| Documents Pending |
10-30% (based on checklist) |
| Ready for Prep |
35% |
| AI Analysis |
40% |
| In Prep |
50% |
| Pending Client Response |
55% |
| Ready for Review |
70% |
| In Review |
75% |
| Approved |
85% |
| Pending Signature |
90% |
| Ready to File |
95% |
| Complete |
100% |
3.5.2 Preliminary Tax Preparation
| ID |
Requirement |
Priority |
| WFL-010 |
System shall generate preliminary tax calculations based on extracted data |
Must Have |
| WFL-011 |
System shall integrate with tax preparation software for calculations (software TBD) |
Must Have |
| WFL-012 |
System shall apply firm-defined guidelines for analysis (protected from client-facing exposure) |
Must Have |
| WFL-013 |
System shall generate preparer report highlighting key items |
Must Have |
3.5.3 Workflow Exception Handling
| ID |
Requirement |
Priority |
| WFL-040 |
All workflow state transitions shall have exception handling for unexpected conditions |
Must Have |
| WFL-041 |
Items that cannot be automatically classified shall route to "Needs Review" queue |
Must Have |
| WFL-042 |
System shall alert when items remain in exception state beyond configurable threshold |
Should Have |
| WFL-043 |
System shall log all exception conditions for process improvement analysis |
Should Have |
3.5.4 Priority and Rush Processing
| ID |
Requirement |
Priority |
| WFL-050 |
System shall support priority queue for expedited processing |
Should Have |
| WFL-051 |
System shall support rush fee based on turnaround requested (24-hour, 48-hour) |
Should Have |
| WFL-052 |
Priority returns shall be visually distinguished in all queue views |
Should Have |
3.6 Accountant Review
3.6.1 Interactive Review Interface
| ID |
Requirement |
Priority |
| REV-001 |
System shall provide review interface showing return summary with drill-down |
Must Have |
| REV-002 |
System shall provide access to all source documents during review |
Must Have |
| REV-003 |
System shall highlight AI-flagged items for attention |
Must Have |
| REV-004 |
System shall support reviewer annotations and notes |
Must Have |
| REV-005 |
System shall track reviewer changes from AI preliminary work |
Should Have |
3.6.2 AI Q&A Assistance
| ID |
Requirement |
Priority |
| REV-010 |
System shall provide AI assistant for reviewer questions (interactive mode) |
Must Have |
| REV-011 |
AI shall have access to all client documents and extracted data |
Must Have |
| REV-012 |
AI shall provide guidance based on tax code and firm guidelines |
Must Have |
| REV-013 |
AI responses shall cite source documents when applicable |
Should Have |
| REV-014 |
System shall log all AI interactions for audit purposes |
Must Have |
3.6.3 Batch AI Processing
| ID |
Requirement |
Priority |
| REV-020 |
Preparer can flag items for batch AI analysis with annotations |
Should Have |
| REV-021 |
Batch items shall be processed during off-peak hours for efficiency |
Should Have |
| REV-022 |
Preparer can provide context/guidance to direct batch AI research |
Should Have |
| REV-023 |
Batch results shall be queued for preparer review next business day |
Should Have |
| REV-024 |
System shall distinguish between interactive (real-time) and batch (overnight) AI modes |
Should Have |
Note: Batch API processing is efficient for non-urgent tasks. Use batch mode for complex research questions that don't require immediate response.
3.7 EA/CPA Final Review
3.7.1 Package Review
| ID |
Requirement |
Priority |
| FIN-001 |
System shall present complete package to EA/CPA for final review |
Must Have |
| FIN-002 |
System shall provide checklist of required review items |
Must Have |
| FIN-003 |
EA/CPA shall have access to AI assistant for questions |
Must Have |
| FIN-004 |
System shall require explicit approval before package release |
Must Have |
| FIN-005 |
System shall log approval with timestamp and approver identity |
Must Have |
3.8 Client Delivery
3.8.1 Package Generation
| ID |
Requirement |
Priority |
| DEL-001 |
System shall generate complete tax return package |
Must Have |
| DEL-002 |
System shall generate cover letter from approved templates |
Must Have |
| DEL-003 |
System shall generate Form 8879 (e-file authorization) |
Must Have |
| DEL-004 |
System shall generate invoice |
Must Have |
| DEL-005 |
System shall generate pre-filled payment authorization if applicable |
Should Have |
| DEL-006 |
System shall generate estimated tax vouchers (1040-ES, state equivalents) |
Must Have |
3.8.2 Google Workspace Signature Integration
| ID |
Requirement |
Priority |
| DEL-010 |
System shall send package via Google Workspace for client signature |
Must Have |
| DEL-011 |
System shall configure signing order (8879 before other documents) |
Must Have |
| DEL-012 |
System shall track signature status |
Must Have |
| DEL-013 |
System shall send reminders for unsigned documents |
Should Have |
| DEL-014 |
System shall retrieve signed documents and store with client record |
Must Have |
3.9 E-Filing and Status Management
📋 Technical Reference: For the complete E-Filing Transmission state machine (14 states including rejection handling), see PROCESS_FLOWS.md.
3.9.1 E-File Transmission
| ID |
Requirement |
Priority |
| EFL-001 |
System shall integrate with third-party e-file transmitter (Column Tax, April, or Drake) |
Must Have |
| EFL-002 |
System shall transmit returns upon receipt of signed Form 8879 |
Must Have |
| EFL-003 |
System shall transmit federal and state returns |
Must Have |
| EFL-004 |
System shall store transmission confirmation |
Must Have |
3.9.2 Status Monitoring
| ID |
Requirement |
Priority |
| EFL-010 |
System shall poll for acknowledgement status every 6 hours during filing season |
Must Have |
| EFL-011 |
System shall update return status upon acceptance |
Must Have |
| EFL-012 |
System shall notify client upon acceptance |
Must Have |
| EFL-013 |
System shall store acceptance confirmation number |
Must Have |
3.9.3 Rejection Handling
| ID |
Requirement |
Priority |
| EFL-020 |
System shall parse rejection error codes |
Must Have |
| EFL-021 |
System shall categorize rejections (data mismatch, missing info, duplicate, technical) |
Must Have |
| EFL-022 |
System shall auto-correct technical errors where possible |
Should Have |
| EFL-023 |
System shall assign rejections requiring human review to preparer queue |
Must Have |
| EFL-024 |
System shall notify client when additional information needed |
Must Have |
| EFL-025 |
System shall track rejection resolution deadline |
Must Have |
| EFL-026 |
System shall flag duplicate filing rejections for fraud review |
Must Have |
3.10 Estimated Tax Management
3.10.1 Voucher Generation
| ID |
Requirement |
Priority |
| EST-001 |
System shall calculate quarterly estimated tax amounts |
Must Have |
| EST-002 |
System shall generate federal Form 1040-ES vouchers |
Must Have |
| EST-003 |
System shall generate state estimated tax vouchers |
Must Have |
| EST-004 |
System shall include vouchers in client delivery package |
Must Have |
3.10.2 Calendar Integration
| ID |
Requirement |
Priority |
| EST-010 |
System shall generate ICS calendar events for each quarterly due date |
Must Have |
| EST-011 |
Calendar events shall include payment amount and instructions |
Must Have |
| EST-012 |
System shall provide one-click calendar add (Google, Outlook, Apple) |
Should Have |
3.10.3 Reminder Notifications
| ID |
Requirement |
Priority |
| EST-020 |
System shall send reminder notification 14 days before due date |
Must Have |
| EST-021 |
System shall send reminder notification 3 days before due date |
Must Have |
| EST-022 |
Reminders shall include payment amount and link to IRS Direct Pay |
Must Have |
| EST-023 |
System shall support client preference for reminder method (email, SMS, both) |
Should Have |
3.10.4 Payment Tracking
| ID |
Requirement |
Priority |
| EST-030 |
System shall allow client to mark estimated payments as made |
Should Have |
| EST-031 |
System shall track payment confirmation for preparer reference |
Should Have |
3.11 Extension Management
3.11.1 Extension Filing
| ID |
Requirement |
Priority |
| EXT-001 |
System shall generate Form 4868 (individual extension) |
Must Have |
| EXT-002 |
System shall track extension deadline (October 15) |
Must Have |
| EXT-003 |
System shall calculate and include estimated payment with extension |
Must Have |
| EXT-004 |
System shall transmit extension electronically |
Must Have |
3.12 Amendment Handling
3.12.1 Amended Return Workflow
| ID |
Requirement |
Priority |
| AMD-001 |
System shall support creation of amended returns (Form 1040-X) |
Should Have |
| AMD-002 |
System shall link amended return to original return |
Should Have |
| AMD-003 |
System shall track amendment reason |
Should Have |
3.13 Billing and Payments
3.13.1 Invoice Generation
| ID |
Requirement |
Priority |
| BIL-001 |
System shall generate invoices based on firm fee schedule |
Must Have |
| BIL-002 |
System shall support complexity-based pricing adjustments |
Should Have |
| BIL-003 |
System shall track invoice status (pending, paid, overdue) |
Must Have |
3.13.2 Payment Processing
| ID |
Requirement |
Priority |
| BIL-010 |
System shall integrate with payment processor (Stripe) |
Must Have |
| BIL-011 |
System shall support credit card payments |
Must Have |
| BIL-012 |
System shall support ACH payments with reduced fees |
Should Have |
| BIL-013 |
System shall send payment confirmation |
Must Have |
| BIL-014 |
System shall send overdue payment reminders |
Should Have |
4. Compliance and Regulatory Requirements
4.1 IRS Requirements
4.1.1 Circular 230 Compliance
| ID |
Requirement |
Priority |
| CIR-001 |
System shall support due diligence documentation for all returns |
Must Have |
| CIR-002 |
System shall maintain preparer and reviewer sign-off records |
Must Have |
| CIR-003 |
System shall log all client communications |
Must Have |
| CIR-004 |
System shall maintain competency records for preparers (if applicable) |
Should Have |
4.1.2 PTIN Tracking
| ID |
Requirement |
Priority |
| PTIN-001 |
System shall store PTIN for all preparers |
Must Have |
| PTIN-002 |
System shall track PTIN expiration dates |
Must Have |
| PTIN-003 |
System shall alert when PTIN renewal is needed |
Should Have |
| PTIN-004 |
System shall prevent return preparation by users with expired PTINs |
Must Have |
| ID |
Requirement |
Priority |
| WISP-001 |
System architecture shall comply with IRS Publication 4557 requirements |
Must Have |
| WISP-002 |
System shall support documentation of security policies |
Must Have |
| WISP-003 |
System shall provide audit logs for security reviews |
Must Have |
| WISP-004 |
System shall support incident response documentation |
Must Have |
4.1.4 E-File Provider Requirements
| ID |
Requirement |
Priority |
| EFP-001 |
System shall comply with IRS Publication 3112 (e-file providers) |
Must Have |
| EFP-002 |
System shall maintain e-file acceptance records |
Must Have |
| EFP-003 |
System shall store acknowledgement files per IRS requirements |
Must Have |
4.2 Audit Trail and Logging
| ID |
Requirement |
Priority |
| AUD-001 |
System shall log all user actions with timestamp and user identity |
Must Have |
| AUD-002 |
System shall log all document access |
Must Have |
| AUD-003 |
System shall log all data modifications with before/after values |
Must Have |
| AUD-004 |
System shall log all AI interactions |
Must Have |
| AUD-005 |
Logs shall be immutable (append-only) |
Must Have |
| AUD-006 |
Logs shall be retained for minimum 7 years |
Must Have |
| AUD-007 |
System shall support log export for audit purposes |
Must Have |
4.3 Data Retention
| ID |
Requirement |
Priority |
| RET-001 |
System shall retain tax returns and supporting documents for minimum 7 years |
Must Have |
| RET-002 |
System shall retain engagement letters permanently |
Must Have |
| RET-003 |
System shall implement automated lifecycle policies (hot/warm/cold storage) |
Should Have |
| RET-004 |
System shall support legal hold to prevent deletion when required |
Must Have |
| RET-005 |
System shall implement secure deletion when retention period expires |
Must Have |
4.4 Privacy Requirements
4.4.1 Gramm-Leach-Bliley Act (GLBA)
| ID |
Requirement |
Priority |
| GLB-001 |
System shall implement safeguards for client financial information |
Must Have |
| GLB-002 |
System shall restrict access to client data on need-to-know basis |
Must Have |
| GLB-003 |
System shall support privacy notice delivery |
Should Have |
4.4.2 State Privacy Laws
| ID |
Requirement |
Priority |
| SPL-001 |
System shall comply with California Consumer Privacy Act (CCPA) if applicable |
Must Have |
| SPL-002 |
System shall support data subject access requests |
Should Have |
| SPL-003 |
System shall support data deletion requests (subject to retention requirements) |
Should Have |
5. Security Requirements
5.1 Authentication and Access Control
| ID |
Requirement |
Priority |
| SEC-001 |
System shall require multi-factor authentication for all staff users |
Must Have |
| SEC-002 |
System shall implement role-based access control (RBAC) |
Must Have |
| SEC-003 |
System shall support session timeout after inactivity |
Must Have |
| SEC-004 |
System shall log all authentication attempts (successful and failed) |
Must Have |
| SEC-005 |
System shall lock accounts after configurable failed login attempts |
Must Have |
Defined Roles:
1) Admin — System configuration, user management
2) Preparer — Document access, return preparation, client communication
3) Reviewer — All preparer permissions plus approval authority
4) EA/CPA — All reviewer permissions plus final sign-off authority
5) Client — Own documents and returns only
5.2 Encryption
| ID |
Requirement |
Priority |
| ENC-001 |
All data shall be encrypted at rest (AES-256) |
Must Have |
| ENC-002 |
All data shall be encrypted in transit (TLS 1.3) |
Must Have |
| ENC-003 |
Database encryption keys shall be managed via AWS KMS |
Must Have |
| ENC-004 |
Client SSN and financial account numbers shall use field-level encryption |
Must Have |
5.3 Network Security
| ID |
Requirement |
Priority |
| NET-001 |
Application shall be deployed in private subnets |
Must Have |
| NET-002 |
Database shall not be publicly accessible |
Must Have |
| NET-003 |
Web application firewall (WAF) shall be implemented |
Must Have |
| NET-004 |
DDoS protection shall be implemented |
Should Have |
5.4 Incident Response
| ID |
Requirement |
Priority |
| INC-001 |
System shall support security incident logging |
Must Have |
| INC-002 |
System shall support alerting on suspicious activity |
Should Have |
| INC-003 |
System shall support forensic data export |
Should Have |
5.5 Firm Intellectual Property Protection
| ID |
Requirement |
Priority |
| IPP-001 |
Firm proprietary guidelines and checklists shall be stored separately from client data |
Must Have |
| IPP-002 |
AI responses to clients shall not expose specific firm guidelines or methodologies |
Must Have |
| IPP-003 |
Firm knowledge base shall only be accessible by staff AI sessions, not client-facing interfaces |
Must Have |
| IPP-004 |
AI responses shall cite "firm guidelines" without exposing proprietary rule content |
Should Have |
6. Infrastructure and Scalability
6.1 Architecture Overview
📋 Technical Reference: For the complete logical data model (35+ entities with full attribute specifications, relationships, and ER diagrams), see DATA_MODEL.md.
The system shall be deployed on AWS with the following components:
| Component |
Technology |
Purpose |
| Application Tier |
ECS/EKS with Auto-scaling |
API and web application hosting |
| Transactional Database |
Aurora PostgreSQL Serverless v2 |
Client records, return status, workflow state |
| Analytical Database |
Snowflake |
Reporting, AI/ML feature store, historical analysis |
| Document Storage |
S3 with lifecycle policies |
Tax documents, signed forms, uploads |
| AI/ML |
AWS Bedrock (Claude) |
Document analysis, Q&A, preliminary review |
| Search |
OpenSearch |
Document and client search |
| Cache |
ElastiCache (Redis) |
Session management, frequently accessed data |
| Message Queue |
SQS |
Async processing (document extraction, notifications) |
6.2 Multi-Region Deployment
| ID |
Requirement |
Priority |
| INF-001 |
Primary region shall be us-east-1 |
Must Have |
| INF-002 |
Disaster recovery region shall be us-west-2 |
Must Have |
| INF-003 |
Aurora Global Database shall replicate to DR region |
Must Have |
| INF-004 |
S3 Cross-Region Replication shall be enabled for document storage |
Must Have |
| INF-005 |
Route 53 health checks shall enable automatic failover |
Must Have |
| INF-006 |
DR region shall be warm standby (deployable within 1 hour) |
Should Have |
6.3 Scalability Requirements
| ID |
Requirement |
Priority |
| SCL-001 |
System shall support 10x normal load during tax season (January-April) |
Must Have |
| SCL-002 |
Aurora shall scale from 0.5 to 128 ACUs based on demand |
Must Have |
| SCL-003 |
Application tier shall auto-scale based on CPU and request metrics |
Must Have |
| SCL-004 |
System shall scale to near-zero during off-season for efficiency |
Should Have |
| ID |
Requirement |
Priority |
| PRF-001 |
API response time shall be less than 500ms for 95th percentile |
Should Have |
| PRF-002 |
Document upload shall complete within 30 seconds for files up to 50MB |
Should Have |
| PRF-003 |
AI document extraction shall complete within 60 seconds per document |
Should Have |
| PRF-004 |
Search results shall return within 2 seconds |
Should Have |
6.5 Availability Requirements
| ID |
Requirement |
Priority |
| AVL-001 |
System shall target 99.9% uptime during tax season |
Must Have |
| AVL-002 |
Planned maintenance shall occur outside business hours |
Must Have |
| AVL-003 |
System shall provide status page for outage communication |
Should Have |
6.6 Environment Strategy
| Environment |
Purpose |
Data |
| Dev |
Development, unit testing |
Synthetic data only |
| UAT |
User acceptance, integration testing |
Sanitized production data |
| Prod |
Live system |
Real client data |
| ID |
Requirement |
Priority |
| ENV-001 |
System shall support Dev, UAT, and Prod environments |
Must Have |
| ENV-002 |
Production data shall never be used in Dev environment |
Must Have |
| ENV-003 |
UAT shall use sanitized/anonymized production data for realistic testing |
Should Have |
| ENV-004 |
Environment configurations shall be managed separately from code |
Must Have |
6.7 Deployment and CI/CD
| ID |
Requirement |
Priority |
| DEP-001 |
Infrastructure shall be defined as code (AWS CDK or Terraform) |
Must Have |
| DEP-002 |
Automated deployment pipeline via GitHub Actions |
Must Have |
| DEP-003 |
All deployments shall require passing automated tests |
Must Have |
| DEP-004 |
Blue-green deployment for zero-downtime updates |
Should Have |
| DEP-005 |
Automated rollback capability on deployment failure |
Should Have |
7. Integration Requirements
7.1 Tax Software Integration (UltraTax CS)
Note: UltraTax CS has no public API. All integration is achieved via SurePrep's CS Connect, which has native UltraTax integration. See Section 7.9 for SurePrep integration requirements.
| ID |
Requirement |
Priority |
| TXS-001 |
System shall integrate with UltraTax CS via SurePrep API |
Must Have |
| TXS-002 |
Integration shall support data export to UltraTax via SurePrep CS Connect |
Must Have |
| TXS-003 |
Integration shall support import of completed return data via SurePrep |
Must Have |
| TXS-004 |
System shall not attempt direct UltraTax API integration (none available) |
Must Have |
7.2 E-Filing Transmitter
Recommended Provider: Column Tax or April API (modern, API-first)
Fallback: Drake Software (if already in use)
| ID |
Requirement |
Priority |
| EFT-001 |
System shall integrate with e-file transmitter API |
Must Have |
| EFT-002 |
Integration shall support federal transmission |
Must Have |
| EFT-003 |
Integration shall support all state transmissions |
Must Have |
| EFT-004 |
Integration shall support webhook-based status updates |
Should Have |
| EFT-005 |
Integration shall support rejection error code parsing |
Must Have |
7.3 Google Workspace Signatures
| ID |
Requirement |
Priority |
| GSG-001 |
System shall integrate with Google Workspace for e-signatures |
Must Have |
| GSG-002 |
Integration shall support document creation with multiple signature fields |
Must Have |
| GSG-003 |
Integration shall support signing order configuration |
Must Have |
| GSG-004 |
Integration shall support status notifications |
Must Have |
| GSG-005 |
Integration shall retrieve signed documents and store in Drive |
Must Have |
7.4 Payment Processing (Stripe)
| ID |
Requirement |
Priority |
| PAY-001 |
System shall integrate with Stripe API |
Must Have |
| PAY-002 |
Integration shall support payment links |
Must Have |
| PAY-003 |
Integration shall support ACH payments |
Should Have |
| PAY-004 |
Integration shall support webhook notifications |
Must Have |
7.5 Identity Verification (Persona)
| ID |
Requirement |
Priority |
| IDV-001 |
System shall integrate with Persona API |
Must Have |
| IDV-002 |
Integration shall support government ID verification |
Must Have |
| IDV-003 |
Integration shall support selfie/liveness check |
Should Have |
| IDV-004 |
Integration shall return confidence score |
Must Have |
| IDV-005 |
Integration shall support webhook callbacks |
Must Have |
7.6 Google Workspace
| ID |
Requirement |
Priority |
| GWS-001 |
System shall integrate with Google Meet for video verification |
Must Have |
| GWS-002 |
Integration shall support calendar event creation |
Should Have |
| GWS-003 |
Integration shall support Meet recording storage in Drive |
Should Have |
7.7 Email and Notifications
| ID |
Requirement |
Priority |
| EML-001 |
System shall integrate with email service (SES or SendGrid) |
Must Have |
| EML-002 |
System shall support transactional email templates |
Must Have |
| EML-003 |
System shall integrate with SMS service (Twilio) |
Should Have |
| EML-004 |
SMS shall support voice call fallback |
Must Have |
7.8 SmartVault (Client Portal)
SmartVault is the firm's existing client-facing document portal. V1 integrates with SmartVault rather than replacing it.
API Documentation: https://developer.smartvault.com/
| ID |
Requirement |
Priority |
| SMV-001 |
System shall integrate with SmartVault REST API |
Must Have |
| SMV-002 |
Integration shall support OAuth 2.0 authentication |
Must Have |
| SMV-003 |
Integration shall retrieve documents uploaded by clients |
Must Have |
| SMV-004 |
Integration shall upload completed documents to client folders |
Must Have |
| SMV-005 |
Integration shall receive notifications when clients upload documents |
Should Have |
| SMV-006 |
Integration shall support folder structure management |
Should Have |
| SMV-007 |
System shall not replace SmartVault as client portal in V1 |
Must Have |
Integration Pattern:
- Monitor SmartVault for new client uploads
- Retrieve documents for processing
- Push completed returns and deliverables back to SmartVault
- Maintain SmartVault as client-facing interface
7.9 SurePrep (Document Processing)
SurePrep handles document OCR, data extraction, and UltraTax CS integration via native CS Connect. V1 integrates with SurePrep rather than replacing it.
API Documentation: https://corp.sureprep.com/products/api/
Products in Use:
- 1040SCAN - OCR and data extraction from tax documents
- TaxCaddy - Client document request lists (may overlap with SmartVault)
- SPbinder - Workpaper organization
- CS Connect - Native UltraTax CS data population
| ID |
Requirement |
Priority |
| SPR-001 |
System shall integrate with SurePrep REST API |
Must Have |
| SPR-002 |
Integration shall support HTTP Basic + API key authentication |
Must Have |
| SPR-003 |
Integration shall create and manage binders |
Must Have |
| SPR-004 |
Integration shall upload documents for processing |
Must Have |
| SPR-005 |
Integration shall retrieve extracted data from processed documents |
Must Have |
| SPR-006 |
Integration shall receive event notifications (status changes, uploads) |
Should Have |
| SPR-007 |
Integration shall retrieve processed PDFs and reports |
Should Have |
| SPR-008 |
System shall not replace SurePrep OCR/extraction in V1 |
Must Have |
| SPR-009 |
UltraTax CS data population shall continue via SurePrep CS Connect |
Must Have |
Integration Pattern:
- Retrieve documents from SmartVault
- Push documents to SurePrep for OCR/extraction
- Retrieve extracted data for AI analysis and enhancement
- SurePrep pushes data to UltraTax via CS Connect (existing flow)
- Our system adds AI layer on top of SurePrep extractions
Future Consideration: SurePrep replacement would require:
1. Building equivalent OCR/extraction (feasible with Bedrock/Claude)
2. Solving UltraTax integration (no API - major blocker)
8. User Experience Requirements
8.1 Accessibility Standards
| ID |
Requirement |
Priority |
| ACC-001 |
Client portal shall comply with WCAG 2.1 Level AA |
Must Have |
| ACC-002 |
All interfaces shall support screen readers |
Must Have |
| ACC-003 |
Color contrast shall meet accessibility standards |
Must Have |
| ACC-004 |
Font sizes shall be adjustable |
Should Have |
| ACC-005 |
All functionality shall be keyboard-accessible |
Must Have |
8.2 Client Portal
| ID |
Requirement |
Priority |
| PRT-001 |
Portal shall be mobile-responsive |
Must Have |
| PRT-002 |
Portal shall provide clear progress indicators |
Must Have |
| PRT-003 |
Portal shall prominently display help/contact options |
Must Have |
| PRT-004 |
Portal shall support document upload from mobile camera |
Should Have |
| PRT-005 |
Portal shall display status of return in plain language |
Must Have |
8.3 Staff Interface
| ID |
Requirement |
Priority |
| STF-001 |
Staff interface shall provide dashboard with workload overview |
Must Have |
| STF-002 |
Staff interface shall support keyboard shortcuts for common actions |
Should Have |
| STF-003 |
Staff interface shall provide quick access to AI assistant |
Must Have |
| STF-004 |
Staff interface shall support split-screen document review |
Should Have |
| STF-010 |
Staff interface shall be accessible on mobile devices |
Should Have |
| STF-011 |
Mobile staff view shall support queue review and note-taking |
Should Have |
| STF-012 |
Mobile staff view shall support viewing (not editing) return details |
Should Have |
| STF-013 |
Mobile notifications for urgent items (rejections, client responses) |
Should Have |
8.4 Senior Citizen Accommodations
| ID |
Requirement |
Priority |
| SEN-001 |
Default font size shall be minimum 16px |
Must Have |
| SEN-002 |
Phone support option shall be prominently displayed |
Must Have |
| SEN-003 |
SMS verification shall always offer voice call alternative |
Must Have |
| SEN-004 |
Paper mail option shall be available for document submission |
Should Have |
| SEN-005 |
Error messages shall be in plain language (not technical codes) |
Must Have |
9. AI Capabilities
| ID |
Requirement |
Priority |
| AIE-001 |
AI shall extract data from W-2 forms |
Must Have |
| AIE-002 |
AI shall extract data from 1099 variants (INT, DIV, B, MISC, NEC, R, etc.) |
Must Have |
| AIE-003 |
AI shall extract data from 1098 variants (mortgage interest, tuition) |
Must Have |
| AIE-004 |
AI shall extract data from K-1 schedules |
Must Have |
| AIE-005 |
AI shall extract data from brokerage statements |
Should Have |
| AIE-006 |
AI shall flag low-confidence extractions for human review |
Must Have |
| AIE-007 |
AI shall learn from human corrections over time |
Should Have |
9.2 Preliminary Analysis
| ID |
Requirement |
Priority |
| AIA-001 |
AI shall compare current year to prior year data |
Must Have |
| AIA-002 |
AI shall flag significant changes (income, deductions, life events) |
Must Have |
| AIA-003 |
AI shall identify potential missing documents |
Must Have |
| AIA-004 |
AI shall suggest questions for client clarification |
Must Have |
| AIA-005 |
AI shall apply firm-defined guidelines for flagging items |
Must Have |
9.3 Interactive Q&A
| ID |
Requirement |
Priority |
| AIQ-001 |
AI shall answer preparer questions about specific returns |
Must Have |
| AIQ-002 |
AI shall have access to all documents and extracted data for the return |
Must Have |
| AIQ-003 |
AI shall cite source documents in responses |
Should Have |
| AIQ-004 |
AI shall provide tax code references when applicable |
Should Have |
| AIQ-005 |
AI shall clearly indicate when it is uncertain |
Must Have |
9.4 Skills Framework
| ID |
Requirement |
Priority |
| SKL-001 |
System shall support modular tax skills organized by year and jurisdiction |
Must Have |
| SKL-002 |
Skills shall be version-controlled and auditable |
Must Have |
| SKL-003 |
Skills shall be updateable annually for tax law changes |
Must Have |
| SKL-004 |
Skills shall include federal and state-specific rules |
Must Have |
Proposed Skills Structure:
/skills
├── /federal
│ ├── /2024
│ │ ├── /1040
│ │ ├── /schedules
│ │ └── /credits
│ └── /2025
│ └── ...
├── /state
│ ├── /2024
│ │ ├── /CA
│ │ ├── /NY
│ │ └── /...
│ └── /2025
│ └── ...
└── /firm
├── /guidelines
├── /checklists
└── /templates
9.5 Document Analysis Processing
| ID |
Requirement |
Priority |
| AIP-001 |
System shall support batch (overnight) document analysis as default |
Must Have |
| AIP-002 |
System shall support expedited (immediate) document analysis on demand |
Must Have |
| AIP-003 |
System shall track expedited analysis quota per client account |
Must Have |
| AIP-004 |
System shall display document analysis status (pending, queued, processing, complete) |
Must Have |
| AIP-005 |
System shall display remaining expedited quota to users |
Should Have |
| AIP-006 |
System shall integrate with Stripe for overage billing |
Should Have |
Processing Tiers:
| Tier |
Timing |
Description |
| Batch (Default) |
Overnight processing |
Included in service |
| Expedited |
Immediate (~30 sec/doc) |
For urgent document analysis |
Processing Model:
- All client accounts include expedited analyses each month
- Overnight batch processing runs via Airflow DAG (see ARCHITECTURE.md Section 15)
User Experience:
- Documents show status badges: "Pending Analysis", "Queued", "Processing", "Complete"
- Banner on upload: "X documents pending. Overnight batch included, or analyze now."
- Users can choose between immediate processing or overnight batch
10. Implementation Plan
10.1 Development Methodology
This project will be developed using an AI-assisted development model:
1) Human Architect + AI Developer — System architecture decisions made by human; implementation executed via Claude Code
2) Iterative Development — Each phase delivers working functionality
3) Continuous Integration — Automated testing and deployment pipelines from day one
4) Documentation-First — Requirements and design documented before implementation
10.2 Implementation Timeline
Target: January 2027 Filing Season (processing 2026 returns)
| Phase |
Timing |
Activities |
Firm Time Required |
| 1. Discovery |
Now - Jan 10 '26 |
Answer 4 open questions, gather sample documents and firm guidelines, workflow walkthrough |
~3 hours total |
| 2. Development & QA |
Jan - Apr '26 |
Build complete system during 2026 filing season |
None (firm focuses on 2025 returns) |
| 3. Integration Testing |
May '26 |
E-filing transmitter, Persona, Stripe, Google Workspace integrations |
None |
| 4. Staff Orientation + UAT |
Jun - Aug '26 |
2-hour system orientation, structured testing with synthetic data, friends/family as test clients |
Moderate |
| 5. Training & Soft Launch |
Sep - Oct '26 |
Comprehensive staff training on finalized system, select early adopter clients |
Moderate |
| 6. Go-Live |
Oct '26 |
Production launch |
Ongoing |
| First Full Season |
Jan '27 |
Processing 2026 returns in production |
Ongoing |
10.3 Discovery Phase Details
Discovery must be completed before development begins. Required inputs:
| Item |
Method |
Time |
| Answer 4 open questions (tax software, volumes, entity mix, states) |
Questionnaire or 30-min call |
30 min |
| Sample documents (W-2, 1099, K-1, etc.) |
Firm sends sanitized examples |
1 hr |
| Firm guidelines and checklists |
Export existing docs |
30 min |
| Workflow walkthrough |
Brief call: "Walk me through a typical return" |
1 hr |
10.4 UAT Strategy
Test Data Approach:
1) Synthetic Data — Create test scenarios based on real patterns, not actual client data (privacy/compliance)
2) Prior Season Replay — Simulate 2025 tax season workflows with test email addresses
3) Friends/Family Participation — Volunteer as fake clients using sample documents to test client portal experience
4) Complex Scenarios — Develop synthetic cases for K-1s, multi-state, business returns (not available from friends/family)
Orientation Before UAT:
Staff receive 2-hour orientation before testing begins. This ensures:
- Understanding of system concepts and workflow
- Informed feedback during testing
- Structured testing against expected behaviors
10.5 Critical Path Items
The following items have lead times independent of development:
| Item |
Lead Time |
When to Start |
| E-filing transmitter vendor selection |
2-4 weeks |
Discovery phase |
| Persona account setup |
1-2 weeks |
Discovery phase |
| Stripe account setup |
1 week |
Discovery phase |
| Tax software API access |
Variable |
Discovery phase |
| Security review (WISP validation) |
2-3 weeks |
During development |
Recommendation: Initiate vendor conversations during Discovery to prevent integration delays.
10.6 Post-MVP Roadmap
| Release |
Scope |
Target |
| v1.1 |
Business entity support (1120S, 1065) |
Post-first season |
| v1.2 |
Multi-state enhancements |
+2 months |
| v1.3 |
Advanced analytics dashboard |
+2 months |
| v2.0 |
Staff scaling features, workload balancing |
+4 months |
11. Appendices
Appendix A: E-Filing Rejection Workflow
flowchart TB
subgraph TRANSMISSION["📤 TRANSMISSION PHASE"]
A["Return Submitted<br/>to Transmitter"] --> B{"Acknowledgement<br/>Received?"}
B -->|"No - 48hrs"| C["⚠️ Alert:<br/>Stuck Transmission"]
C --> D["Manual<br/>Investigation"]
end
subgraph ROUTING["🔀 STATUS ROUTING"]
B -->|"Yes"| E{"Status<br/>Type?"}
E -->|"Accepted"| F["✅ Mark Return<br/>Complete"]
E -->|"Pending"| G["⏳ Queue for<br/>Re-check"]
E -->|"Rejected"| H["❌ Parse<br/>Error Codes"]
end
subgraph ACCEPTED["✅ ACCEPTED FLOW"]
F --> F1["Update Return<br/>Status in System"]
F1 --> F2["Notify Client:<br/>Filing Confirmed"]
F2 --> F3["Store Confirmation<br/>Number"]
F3 --> F4["Archive Return<br/>Package"]
end
subgraph PENDING["⏳ PENDING FLOW"]
G --> G1["Schedule Re-check<br/>in 6 Hours"]
G1 --> B
end
subgraph REJECTED["❌ REJECTION ANALYSIS"]
H --> I{"Error<br/>Category?"}
I -->|"Data Mismatch"| J["SSN/Name/AGI<br/>Issues"]
I -->|"Missing Info"| K["Forms/Schedules<br/>Missing"]
I -->|"Duplicate"| L["🚨 Already Filed<br/>Alert"]
I -->|"Technical"| M["Schema/Format<br/>Issues"]
end
subgraph AUTO_FIX["🔧 AUTO-CORRECTABLE"]
M --> N{"Can System<br/>Auto-Fix?"}
N -->|"Yes"| O["Apply<br/>Correction"]
O --> P["Log Change<br/>for Audit"]
P --> Q["Resubmit<br/>Automatically"]
Q --> A
end
subgraph HUMAN_REVIEW["👤 HUMAN REVIEW REQUIRED"]
N -->|"No"| R["Assign to<br/>Preparer Queue"]
J --> R
K --> R
R --> T["Preparer<br/>Reviews Error"]
T --> U{"Client Info<br/>Needed?"}
U -->|"Yes"| V["Send Client<br/>Request"]
V --> W["Track Response<br/>Deadline"]
W --> X["Client<br/>Responds"]
X --> T
U -->|"No"| Y["Preparer<br/>Corrects Return"]
Y --> Z["Reviewer<br/>Approves Fix"]
Z --> Q
end
subgraph ESCALATION["⚠️ ESCALATION PATH"]
L --> S1["EA/CPA<br/>Fraud Review"]
S1 --> S2{"Legitimate<br/>Filing?"}
S2 -->|"Yes"| R
S2 -->|"No"| S3["Client Contact<br/>Required"]
S3 --> S4["Document<br/>Resolution"]
W -->|"No Response<br/>7 Days"| W1["Escalate to<br/>Account Manager"]
W1 --> W2["Phone<br/>Outreach"]
end
style A fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
style F fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
style F4 fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
style H fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px
style L fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px
style R fill:#fff3e0,stroke:#f57c00,stroke-width:2px
style S1 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
style Q fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
Appendix B: E-Filing Rejection Swimlane
| Step |
System |
Preparer |
Reviewer/EA |
Client |
| 1. Transmit return |
Sends to transmitter |
|
|
|
| 2. Receive acknowledgement |
Parses status |
|
|
|
| 3a. If Accepted |
Updates status, notifies client, archives |
|
|
Receives confirmation |
| 3b. If Pending |
Schedules re-check |
|
|
|
| 3c. If Rejected |
Categorizes error |
|
|
|
| 4. Auto-correctable? |
Applies fix, resubmits |
|
|
|
| 5. Needs human review |
Assigns to queue |
Reviews error |
|
|
| 6. Client info needed? |
Sends request |
Drafts questions |
|
Receives request |
| 7. Client responds |
|
|
|
Provides info |
| 8. Correction made |
|
Makes correction |
|
|
| 9. Review fix |
|
|
Approves correction |
|
| 10. Resubmit |
Transmits corrected return |
|
|
|
| 11. Duplicate/Fraud alert |
Flags for review |
|
Reviews, contacts client |
Contacted if needed |
Appendix C: Identity Verification Workflow
flowchart TB
subgraph ENTRY["🚪 CLIENT ENTRY POINT"]
A["Client Initiates<br/>Access Request"] --> B{"Returning<br/>Client?"}
end
subgraph TIER1["🟢 TIER 1: RETURNING CLIENTS (Low Friction)"]
B -->|"Yes"| C["Match Against<br/>Records"]
C --> D{"Verify:<br/>Name + SSN-4 + DOB<br/>+ Prior Year AGI?"}
D -->|"All Match"| E["✅ Auto-Verified"]
D -->|"Partial Match"| F["Send Magic Link<br/>to Email on File"]
F --> G{"Link Clicked +<br/>Security Question<br/>Answered?"}
G -->|"Yes"| E
G -->|"No/Failed"| H["Escalate to<br/>Tier 2"]
end
subgraph TIER2["🟡 TIER 2: NEW CLIENTS (Moderate Friction)"]
B -->|"No"| I["New Client<br/>Registration"]
H --> I
I --> J["Email<br/>Verification"]
J --> K["Phone Verification<br/>(SMS or Voice Call)"]
K --> L["Upload<br/>Government ID"]
L --> M["Persona<br/>ID Analysis"]
M --> N{"Confidence<br/>Score?"}
N -->|"≥90%"| O["✅ Auto-Verified"]
N -->|"70-89%"| P["Human Review<br/>Queue"]
P --> Q{"Staff<br/>Approves?"}
Q -->|"Yes"| O
Q -->|"No"| R["Escalate to<br/>Tier 3"]
N -->|"<70%"| R
end
subgraph TIER3["🔴 TIER 3: HIGH-RISK (Justified Friction)"]
R --> S["Client Offered<br/>Verification Options"]
S --> T{"Client<br/>Choice?"}
T -->|"Video Call"| U["Schedule<br/>Google Meet"]
T -->|"In-Person"| V["Office Visit<br/>Appointment"]
T -->|"Notarized"| W["Mail Notarized<br/>Affidavit"]
U --> X["Video Call Checklist"]
V --> Y["In-Person ID Check"]
W --> AA["Receive + Verify Affidavit"]
X --> AB{"Staff Confirms?"}
Y --> AB
AA --> AB
AB -->|"Yes"| AC["✅ Verified"]
AB -->|"No"| AD["❌ Access Denied"]
end
style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
style E fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
style O fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
style AC fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
style AD fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px
Appendix D: Identity Verification Swimlane
| Step |
System |
Staff |
Client |
| TIER 1: Returning Clients |
|
|
|
| 1. Client initiates access |
Checks client database |
|
Logs in |
| 2. Match records |
Compares Name + SSN-4 + DOB + Prior AGI |
|
|
| 3a. All match |
Grants access |
|
Proceeds |
| 3b. Partial match |
Sends magic link email |
|
Clicks link |
| 4. Security question |
Validates answer |
|
Answers |
| 5a. Success |
Grants access |
|
Proceeds |
| 5b. Failure |
Escalates to Tier 2 |
|
|
| TIER 2: New Clients |
|
|
|
| 1. Registration |
Collects basic info |
|
Provides info |
| 2. Email verification |
Sends verification link |
|
Clicks link |
| 3. Phone verification |
Sends SMS or voice call |
|
Enters code |
| 4. ID upload |
Provides upload interface |
|
Uploads ID photo |
| 5. ID analysis |
Sends to Persona, receives score |
|
|
| 6a. Score ≥90% |
Grants access |
|
Proceeds |
| 6b. Score 70-89% |
Routes to review queue |
Reviews ID, approves/denies |
|
| 6c. Score <70% |
Escalates to Tier 3 |
|
|
| TIER 3: High-Risk |
|
|
|
| 1. Present options |
Shows verification choices |
|
Selects option |
| 2a. Video call |
Schedules Google Meet |
Conducts verification call |
Joins call, shows ID |
| 2b. In-person |
Schedules appointment |
Verifies ID in office |
Visits office |
| 2c. Notarized |
Provides affidavit template |
Verifies notarized document |
Mails affidavit |
| 3. Final decision |
Records outcome |
Makes verification decision |
|
Appendix E: Main Workflow States
| State |
Description |
Next States |
Owner |
| Intake |
Client registered, awaiting documents |
Documents Pending |
System |
| Documents Pending |
Partial documents received |
Ready for Prep, Pending Client Response |
Client |
| Ready for Prep |
All documents received, queued for AI |
AI Analysis |
System |
| AI Analysis |
Automated extraction and preliminary review |
In Prep, Needs Review |
System |
| In Prep |
Human preparer reviewing AI output |
Pending Client Response, Ready for Review |
Preparer |
| Pending Client Response |
Questions sent to client |
In Prep, Ready for Prep |
Client |
| Ready for Review |
Prep complete |
In Review |
Reviewer |
| In Review |
Reviewer examining return |
Approved, Revisions Needed |
Reviewer |
| Revisions Needed |
Reviewer identified issues |
In Prep |
Preparer |
| Approved |
Ready for client delivery |
Pending Signature |
System |
| Pending Signature |
Awaiting Form 8879 |
Ready to File |
Client |
| Ready to File |
Authorized for transmission |
Filed |
System |
| Filed |
Transmitted to IRS/state |
Accepted, Rejected |
System |
| Accepted |
IRS/state acknowledged |
Complete |
System |
| Rejected |
IRS/state rejected |
In Prep |
Preparer |
| Complete |
All deliverables provided |
(Terminal) |
System |
| Needs Review |
Exception state for unclassifiable items |
In Prep (after human review) |
Staff |
Appendix F: Vendor Comparison Matrix
E-Filing Transmitters
| Vendor |
API Quality |
State Coverage |
Webhooks |
Recommendation |
| Column Tax |
Excellent |
All states |
Yes |
Primary |
| April API |
Excellent |
All states |
Yes |
Alternative |
| Drake |
Good |
All states |
Limited |
If already using Drake |
| TPG |
Moderate |
All states |
Limited |
Legacy option |
Identity Verification
| Vendor |
API Quality |
Accessibility |
Recommendation |
| Persona |
Excellent |
Good |
Primary |
| Jumio |
Good |
Moderate |
Alternative |
| Onfido |
Good |
Good |
Alternative |
Appendix G: Compliance Checklist
IRS Requirements
| Requirement |
Reference |
Status |
| Circular 230 compliance |
31 CFR Part 10 |
Pending |
| Valid PTINs for all preparers |
IRS PTIN requirements |
Pending |
| Written Information Security Plan |
Publication 4557 |
Pending |
| E-file provider authorization |
Publication 3112 |
Pending |
| Form 7216 consent process |
26 CFR 301.7216 |
Pending |
| Form 8879 retention |
Rev. Proc. 2004-35 |
Pending |
Data Protection
| Requirement |
Reference |
Status |
| GLBA Safeguards Rule |
16 CFR Part 314 |
Pending |
| Encryption at rest |
WISP requirement |
Pending |
| Encryption in transit |
WISP requirement |
Pending |
| Access controls |
WISP requirement |
Pending |
| Audit logging |
WISP requirement |
Pending |
| Incident response plan |
WISP requirement |
Pending |
| Employee training |
WISP requirement |
Pending |
State Requirements
| Requirement |
Applicable States |
Status |
| CCPA compliance |
California |
Pending |
| State privacy laws |
Various |
Pending |
| State preparer registration |
Various |
Pending |
Document History
| Version |
Date |
Author |
Changes |
| 1.0 Draft |
December 22, 2025 |
[Author] |
Initial draft |
| 1.1 Draft |
December 23, 2025 |
[Author] |
Requirements review feedback incorporated: client data portability, expanded assumptions, additional document formats (DOCX/XLSX), proactive client notifications, AI Analysis workflow state, progress tracking, batch AI processing, workflow exception handling, rush processing, firm IP protection, Dev/UAT/Prod environments, CI/CD requirements, mobile staff interface, AI model tier strategy. Revised Section 11 with implementation plan focusing on zero-disruption timeline and UAT strategy. |
| 1.2 Draft |
December 23, 2025 |
[Author] |
Added reference to bookkeeping module (Section 1.2). Bookkeeping requirements tracked separately in bookkeeping_requirements.md to allow independent phasing. |
| 1.3 Draft |
December 23, 2025 |
[Author] |
Client input incorporated: UltraTax CS (Section 2.1), ~1,000 returns/year with 30% growth trajectory (Section 2.2), full-spectrum entity mix (Section 2.3), existing software stack - SmartVault, SurePrep, UltraTax (Section 2.5). Added SmartVault integration (Section 7.8), SurePrep integration (Section 7.9). V1 strategy: integrate with existing tools, do not replace. |
| 1.4 Draft |
December 23, 2025 |
[Author] |
Added Related Technical Documentation section linking to DATA_MODEL.md and PROCESS_FLOWS.md. Added technical reference callouts throughout document pointing to detailed state machines and data model for: Document Management (Section 3.3), Identity Verification (Section 3.2.2), Return Status Management (Section 3.5.1), E-Filing (Section 3.9), and Infrastructure (Section 6.1). |
This document is a living specification and will be updated as follow-up questions are answered and requirements are refined.