Skip to content

Tax Practice AI - Process Flows and State Machines

Version 1.0 | December 2024

Overview

This document defines the state machines and process flows for the Tax Practice AI system. It provides visual documentation of entity lifecycles and business processes using Mermaid diagram syntax.

Related Documentation: - DATA_MODEL.md - Entity definitions and relationships - ARCHITECTURE.md - System architecture - tax_practice_ai_requirements.md - Full requirements

Table of Contents

State Machines: 1. Tax Return Lifecycle 2. Document Lifecycle 3. E-Filing Transmission Lifecycle 4. Identity Verification Lifecycle

Process Flows: 5. End-to-End Tax Return Workflow 6. Document Processing Flow 7. E-Filing and Rejection Handling 8. Client Onboarding Flow

1. Tax Return Lifecycle State Machine

The tax return workflow state machine defines all possible states a return can be in and the valid transitions between states.

1.1 State Diagram

stateDiagram-v2
    [*] --> Intake: Return Created

    Intake --> DocumentsPending: First Document Uploaded

    DocumentsPending --> DocumentsPending: Additional Documents
    DocumentsPending --> ReadyForPrep: All Docs Received
    DocumentsPending --> PendingClientResponse: Missing Docs Requested

    PendingClientResponse --> DocumentsPending: Client Uploads Docs
    PendingClientResponse --> InPrep: Response Received (during prep)

    ReadyForPrep --> AIAnalysis: Queued for AI

    AIAnalysis --> InPrep: Analysis Complete
    AIAnalysis --> NeedsReview: Exception Detected

    NeedsReview --> InPrep: Exception Resolved
    NeedsReview --> InPrep: Staff Review Complete

    InPrep --> PendingClientResponse: Questions Sent to Client
    InPrep --> ReadyForReview: Prep Complete
    InPrep --> NeedsReview: Issue Found

    ReadyForReview --> InReview: Reviewer Assigned

    InReview --> Approved: Review Passed
    InReview --> RevisionsNeeded: Issues Found

    RevisionsNeeded --> InPrep: Preparer Notified

    Approved --> PendingFinalQA: Queued for AI QA

    PendingFinalQA --> PendingSignature: QA Passed
    PendingFinalQA --> RevisionsNeeded: QA Found Issues

    PendingSignature --> PendingSignature: Reminder Sent
    PendingSignature --> ReadyToFile: 8879 Signed

    ReadyToFile --> Filed: Transmitted to IRS

    Filed --> Accepted: IRS Accepted
    Filed --> Rejected: IRS Rejected

    Rejected --> InPrep: Correction Needed

    Accepted --> Complete: Deliverables Sent

    Complete --> [*]

1.2 State Definitions

State Progress % Owner Description
Intake 5% System Return created, awaiting first document
DocumentsPending 10-30% Client Documents being collected
PendingClientResponse Variable Client Waiting for client input
ReadyForPrep 35% System All docs received, queued for AI
AIAnalysis 40% System AI extracting and analyzing
InPrep 50% Preparer Active preparation
NeedsReview 50% Staff Exception requiring human decision
ReadyForReview 70% System Prep complete, awaiting reviewer
InReview 75% Reviewer EA/CPA reviewing return
RevisionsNeeded 60% Preparer Reviewer requested changes
Approved 82% System Review passed, awaiting final QA
PendingFinalQA 85% System Overnight Opus batch QA (FUT-002)
PendingSignature 90% Client Awaiting Form 8879 signature
ReadyToFile 95% System Signed, ready to transmit
Filed 97% System Transmitted, awaiting IRS
Accepted 100% System IRS accepted
Rejected 50% Preparer IRS rejected, needs correction
Complete 100% System All deliverables provided

1.3 Valid Transitions

From State To State Trigger Actor
Intake DocumentsPending First document uploaded System
DocumentsPending ReadyForPrep Checklist complete System
DocumentsPending PendingClientResponse Missing doc request sent System
PendingClientResponse DocumentsPending Document received Client
PendingClientResponse InPrep Response received (during prep) Client
ReadyForPrep AIAnalysis Batch processing starts System
AIAnalysis InPrep Analysis complete System
AIAnalysis NeedsReview Exception detected System
NeedsReview InPrep Issue resolved Staff
InPrep PendingClientResponse Question sent Preparer
InPrep ReadyForReview Prep marked complete Preparer
InPrep NeedsReview Issue found Preparer
ReadyForReview InReview Reviewer starts review Reviewer
InReview Approved Review passed Reviewer
InReview RevisionsNeeded Issues found Reviewer
RevisionsNeeded InPrep Preparer notified System
Approved PendingFinalQA Queued for overnight QA System
PendingFinalQA PendingSignature QA passed (no issues) System
PendingFinalQA RevisionsNeeded QA found issues System
PendingSignature ReadyToFile 8879 signed Client
ReadyToFile Filed Transmission complete System
Filed Accepted IRS acknowledgement IRS
Filed Rejected IRS rejection IRS
Rejected InPrep Correction assigned System
Accepted Complete All deliverables sent System

2. Document Lifecycle State Machine

Documents progress through upload, security scanning, classification, extraction, and verification.

2.1 State Diagram

stateDiagram-v2
    [*] --> Uploaded: Document Received

    Uploaded --> Scanning: Malware Scan Started

    Scanning --> Quarantined: Malware Detected
    Scanning --> Classifying: Scan Clean

    Quarantined --> [*]: Rejected

    Classifying --> Classified: Type Determined
    Classifying --> UnknownType: Cannot Classify

    UnknownType --> Classified: Manual Classification

    Classified --> Extracting: Extraction Started

    Extracting --> Extracted: Extraction Complete
    Extracting --> ExtractionFailed: Cannot Extract

    ExtractionFailed --> ManualEntry: Queue for Manual

    Extracted --> HighConfidence: Score >= 0.95
    Extracted --> MediumConfidence: Score 0.70-0.94
    Extracted --> LowConfidence: Score < 0.70

    HighConfidence --> AutoVerified: Native PDF Match
    HighConfidence --> Verified: Spot Check Passed

    MediumConfidence --> PendingReview: Staff Review Queue

    LowConfidence --> ManualEntry: Requires Manual Entry

    PendingReview --> Verified: Staff Approved
    PendingReview --> ManualEntry: Corrections Needed

    ManualEntry --> Verified: Data Entered

    AutoVerified --> Verified: Mark Complete

    Verified --> [*]: Processing Complete

2.2 State Definitions

State Description Next Actions
Uploaded Document received, pending security Malware scan
Scanning Malware scan in progress Wait for result
Quarantined Malware detected Alert staff, reject
Classifying AI determining document type Assign type
UnknownType Cannot auto-classify Manual classification
Classified Type assigned Begin extraction
Extracting AI/SurePrep extracting data Wait for result
ExtractionFailed Extraction unsuccessful Manual entry
Extracted Raw extraction complete Confidence check
HighConfidence Score >= 0.95 Auto-verify or spot check
MediumConfidence Score 0.70-0.94 Staff review
LowConfidence Score < 0.70 Manual entry
AutoVerified Native PDF auto-verified Mark complete
PendingReview In staff review queue Staff action
ManualEntry Requires manual data entry Staff action
Verified All data verified Ready for use

2.3 Confidence Thresholds

Confidence Level Score Range Action
HIGH >= 0.95 Auto-verify if native PDF, otherwise spot check
GOOD 0.85 - 0.94 Spot check recommended
MODERATE 0.70 - 0.84 Staff review required
LOW 0.50 - 0.69 Manual entry required
VERY_LOW < 0.50 Manual entry required

3. E-Filing Transmission State Machine

The e-filing process from queue through IRS acceptance or rejection handling.

3.1 State Diagram

stateDiagram-v2
    [*] --> Queued: Return Approved & Signed

    Queued --> Transmitting: Batch Started

    Transmitting --> Transmitted: Submission Sent
    Transmitting --> TransmissionError: Network/API Failure

    TransmissionError --> Queued: Retry Scheduled
    TransmissionError --> ManualIntervention: Max Retries Exceeded

    Transmitted --> AwaitingAck: Polling Started

    AwaitingAck --> Accepted: IRS Accepted
    AwaitingAck --> Rejected: IRS Rejected
    AwaitingAck --> Pending: IRS Processing
    AwaitingAck --> Stuck: 48hr No Response

    Pending --> AwaitingAck: Continue Polling

    Stuck --> AwaitingAck: Manual Check
    Stuck --> ManualIntervention: Cannot Resolve

    ManualIntervention --> Queued: Issue Resolved

    Accepted --> [*]: Filing Complete

    Rejected --> AnalyzingRejection: Parse Error Codes

    AnalyzingRejection --> AutoCorrect: Technical Error
    AnalyzingRejection --> PrepReview: Data Error
    AnalyzingRejection --> FraudReview: Duplicate/Fraud

    AutoCorrect --> Queued: Correction Applied

    PrepReview --> ClientContact: Need Client Info
    PrepReview --> Queued: Preparer Corrected

    ClientContact --> PrepReview: Info Received

    FraudReview --> EACPAReview: Escalate

    EACPAReview --> Queued: Legitimate Return
    EACPAReview --> Closed: Fraud Confirmed

    Closed --> [*]: Case Closed

3.2 State Definitions

State Description Auto-Transition
Queued Ready for transmission Yes, batch processing
Transmitting API call in progress Yes, on completion
TransmissionError Network/API failure Yes, retry after delay
Transmitted Successfully sent to IRS Yes, begin polling
AwaitingAck Polling for IRS response Yes, every 6 hours
Pending IRS still processing Yes, continue polling
Stuck No response after 48 hours No, alert staff
ManualIntervention Requires human action No
Accepted IRS accepted return Yes, notify client
Rejected IRS rejected return Yes, analyze
AnalyzingRejection Parsing error codes Yes
AutoCorrect Auto-correctable error Yes
PrepReview Preparer must review No
ClientContact Need client information No
FraudReview Potential fraud indicator No
EACPAReview EA/CPA escalation No
Closed Case closed (fraud) Terminal

3.3 Rejection Categories

Category Description Resolution Path
data_mismatch SSN/name/DOB mismatch Preparer review, client contact
missing_info Required field missing Auto-correct if possible
duplicate Return already filed Fraud review
technical Format/schema error Auto-correct
fraud_indicator IRS fraud flag EA/CPA escalation

4. Identity Verification State Machine

Tiered identity verification for returning and new clients.

4.1 State Diagram

stateDiagram-v2
    [*] --> Initiated: Verification Started

    Initiated --> Tier1: Returning Client
    Initiated --> Tier2: New Client

    state Tier1 {
        [*] --> CheckPriorYearAGI
        CheckPriorYearAGI --> AGIMatch: Match
        CheckPriorYearAGI --> AGIFail: No Match
        AGIMatch --> SecurityQuestion
        SecurityQuestion --> Tier1Pass: Correct
        SecurityQuestion --> MagicLink: Incorrect
        AGIFail --> MagicLink
        MagicLink --> MagicLinkVerified: Link Clicked
        MagicLink --> MagicLinkExpired: 24hr Timeout
        MagicLinkVerified --> Tier1Pass
        MagicLinkExpired --> [*]
        Tier1Pass --> [*]
    }

    Tier1 --> Verified: Tier1Pass
    Tier1 --> Tier2: Tier1 Failed

    state Tier2 {
        [*] --> EmailVerify
        EmailVerify --> PhoneVerify: Email Confirmed
        PhoneVerify --> IDUpload: Phone Confirmed
        IDUpload --> PersonaAnalysis: ID Uploaded
        PersonaAnalysis --> Tier2Pass: Score >= 90%
        PersonaAnalysis --> StaffReview: Score 70-89%
        PersonaAnalysis --> Tier2Fail: Score < 70%
        StaffReview --> Tier2Pass: Approved
        StaffReview --> Tier2Fail: Denied
        Tier2Pass --> [*]
        Tier2Fail --> [*]
    }

    Tier2 --> Verified: Tier2Pass
    Tier2 --> Tier3Options: Tier2 Failed

    state Tier3 {
        [*] --> ChooseMethod
        ChooseMethod --> VideoCall: Client Choice
        ChooseMethod --> InPerson: Client Choice
        ChooseMethod --> Notarized: Client Choice

        VideoCall --> MeetScheduled
        MeetScheduled --> MeetCompleted: Call Done
        MeetScheduled --> MeetNoShow: No Show
        MeetCompleted --> VideoVerified: Confirmed
        MeetCompleted --> VideoFailed: Not Confirmed
        MeetNoShow --> ChooseMethod: Reschedule

        InPerson --> InPersonScheduled
        InPersonScheduled --> InPersonVerified: Confirmed
        InPersonScheduled --> InPersonFailed: Not Confirmed

        Notarized --> AwaitingDocument
        AwaitingDocument --> NotarizedVerified: Valid Document
        AwaitingDocument --> NotarizedFailed: Invalid

        VideoVerified --> [*]
        VideoFailed --> [*]
        InPersonVerified --> [*]
        InPersonFailed --> [*]
        NotarizedVerified --> [*]
        NotarizedFailed --> [*]
    }

    Tier3Options --> Tier3

    Tier3 --> Verified: Tier3 Passed
    Tier3 --> Denied: Tier3 Failed

    Verified --> [*]: Success
    Denied --> [*]: Failure

4.2 Tier Definitions

Tier Target Methods Friction Level
Tier 1 Returning clients Prior year AGI + Security Q + Magic link Low (< 30 sec)
Tier 2 New clients Email + Phone + Government ID Medium (2-3 min)
Tier 3 High risk Video call, In-person, Notarized High (varies)

4.3 Tier 3 Triggers

Trigger Description
Refund > $5,000 to new bank Large refund to unknown account
Persona score 70-89% Moderate identity confidence
Fraud indicators Flags from Persona analysis
Tier 2 failure Failed standard verification
Client request Client prefers higher assurance

5. End-to-End Tax Return Workflow

Complete process flow from client intake through return completion.

5.1 Process Flow Diagram

flowchart TB
    subgraph INTAKE["1. Client Intake"]
        A[Client Contacts Firm] --> B{New or Returning?}
        B -->|New| C[Create Client Record]
        B -->|Returning| D[Retrieve Client Record]
        C --> E[Conflict Check]
        D --> E
        E --> F{Conflict?}
        F -->|Yes| G[Human Review]
        G -->|Waived| H[Document Waiver]
        G -->|Declined| Z1[End - Decline]
        F -->|No| H
        H --> I[Generate Engagement Letter]
        I --> J[Send for Signature]
        J --> K{Signed?}
        K -->|No| L[Send Reminder]
        L --> K
        K -->|Yes| M[Store Signed Engagement]
    end

    subgraph VERIFY["2. Identity Verification"]
        M --> N[Identity Verification]
        N --> O{Verified?}
        O -->|Yes| P[Form 7216 if Needed]
        O -->|No| Q[Escalate to Tier 3]
        Q --> O
        P --> R[Client Onboarded]
    end

    subgraph DOCS["3. Document Collection"]
        R --> S[Generate Doc Checklist]
        S --> T[Create SmartVault Folder]
        T --> U[Send Checklist to Client]
        U --> V[Client Uploads Documents]
        V --> W[Retrieve from SmartVault]
        W --> X[Process Each Document]
        X --> Y{All Docs Received?}
        Y -->|No| AA[Send Missing Doc Request]
        AA --> V
        Y -->|Yes| AB[Mark Ready for Prep]
    end

    subgraph AIANALYSIS["4. AI Analysis"]
        AB --> AC[Queue for AI Analysis]
        AC --> AD[Extract All Documents]
        AD --> AE[Compare to Prior Year]
        AE --> AF[Flag Anomalies]
        AF --> AG[Generate Client Questions]
        AG --> AH[Create Preparer Summary]
        AH --> AIA[Mark AI Complete]
    end

    subgraph PREP["5. Tax Preparation"]
        AIA --> AJ[Assign to Preparer]
        AJ --> AK[Preparer Reviews AI Output]
        AK --> AL{Questions for Client?}
        AL -->|Yes| AM[Send Questions via Portal]
        AM --> AN[Client Responds]
        AN --> AK
        AL -->|No| AO{Ready for Review?}
        AO -->|No| AK
        AO -->|Yes| AP[Submit for Review]
    end

    subgraph REVIEW["6. Review & Approval"]
        AP --> AQ[Assign to Reviewer]
        AQ --> AR[EA/CPA Reviews Return]
        AR --> AS{Approved?}
        AS -->|No| AT[Return for Revisions]
        AT --> AK
        AS -->|Yes| AU[Final Approval]
    end

    subgraph DELIVERY["7. Client Delivery"]
        AU --> AV[Generate Return Package]
        AV --> AW[Generate Form 8879]
        AW --> AX[Generate Invoice]
        AX --> AY[Generate Est Tax Vouchers]
        AY --> AZ[Send via Google Workspace]
        AZ --> BA{All Signed?}
        BA -->|No| BB[Send Signature Reminder]
        BB --> BA
        BA -->|Yes| BC[Retrieve Signed Documents]
        BC --> BD[Process Payment]
    end

    subgraph FILING["8. E-Filing"]
        BD --> BE[Queue for E-Filing]
        BE --> BF[Transmit to IRS/State]
        BF --> BG{Status?}
        BG -->|Accepted| BH[Store Confirmation]
        BG -->|Rejected| BI[Handle Rejection]
        BI --> BJ{Auto-Fix?}
        BJ -->|Yes| BE
        BJ -->|No| AK
        BH --> BK[Notify Client of Acceptance]
    end

    subgraph COMPLETE["9. Completion"]
        BK --> BL[Generate Calendar Events]
        BL --> BM[Schedule Est Tax Reminders]
        BM --> BN[Archive to Cold Storage]
        BN --> BO[Mark Complete]
        BO --> Z2[End - Success]
    end

5.2 Swim Lane Summary

Phase Key Activities Primary Actor
1. Client Intake Conflict check, engagement letter System/Staff
2. Identity Verification Tiered verification Client/System
3. Document Collection Upload, classify, track Client/System
4. AI Analysis Extract, compare, flag System (AI)
5. Tax Preparation Prepare, questions, resolve Preparer
6. Review & Approval EA/CPA review, approve Reviewer
7. Client Delivery Package, signatures, payment Client/System
8. E-Filing Transmit, monitor, handle System
9. Completion Notify, archive, reminders System

6. Document Processing Flow

Detailed flow for processing uploaded tax documents.

6.1 Process Flow Diagram

flowchart TB
    subgraph UPLOAD["1. Upload Phase"]
        A[Document Received] --> B{Source?}
        B -->|SmartVault| C[SmartVault Webhook]
        B -->|Portal| D[Direct Upload API]
        B -->|Email| E[Secure Email Parser]
        C --> F[Retrieve from SmartVault API]
        D --> F
        E --> F
        F --> G[Store in S3]
    end

    subgraph SECURITY["2. Security Phase"]
        G --> H[Queue for Malware Scan]
        H --> I[Scan Document]
        I --> J{Clean?}
        J -->|No| K[Quarantine Document]
        K --> L[Alert Staff]
        L --> Z1[End - Quarantined]
        J -->|Yes| M[Update Status: Clean]
    end

    subgraph CLASSIFY["3. Classification Phase"]
        M --> N[AI Classification]
        N --> O{Type Identified?}
        O -->|No| P[Add to Manual Queue]
        P --> Q[Staff Classifies]
        Q --> R[Update Document Type]
        O -->|Yes| R
        R --> S[Link to Tax Return]
    end

    subgraph EXTRACT["4. Extraction Phase"]
        S --> T{Document Type?}
        T -->|Standard Tax Form| U[Send to SurePrep]
        T -->|Other| V[Internal AI Extraction]
        U --> W[Create SurePrep Binder]
        W --> X[Upload to SurePrep]
        X --> Y[Wait for Processing]
        Y --> AA[Retrieve Extracted Data]
        V --> AB[Claude Bedrock Extraction]
        AA --> AC[Map to Internal Schema]
        AB --> AC
    end

    subgraph VALIDATE["5. Validation Phase"]
        AC --> AD[Calculate Confidence Score]
        AD --> AE{Confidence Level?}
        AE -->|High >= 0.95| AF{Native PDF?}
        AF -->|Yes| AG[Auto-Verify]
        AF -->|No| AH[Spot Check Queue]
        AE -->|Medium 0.70-0.94| AI[Staff Review Queue]
        AE -->|Low < 0.70| AJ[Manual Entry Queue]

        AH --> AK[Staff Spot Check]
        AK --> AL{Approved?}
        AL -->|Yes| AM[Mark Verified]
        AL -->|No| AJ

        AI --> AN[Staff Full Review]
        AN --> AO{Approved?}
        AO -->|Yes| AM
        AO -->|No| AJ

        AJ --> AP[Staff Manual Entry]
        AP --> AM

        AG --> AM
    end

    subgraph COMPLETE["6. Completion Phase"]
        AM --> AQ[Link Extraction to Return]
        AQ --> AR[Update Return Progress]
        AR --> AS[Update Document Checklist]
        AS --> AT{All Docs Complete?}
        AT -->|Yes| AU[Transition: Ready for Prep]
        AT -->|No| AV[Wait for More Docs]
        AU --> Z2[End - Ready]
        AV --> Z3[End - Waiting]
    end

6.2 Document Type Routing

Document Type Extraction Method Typical Confidence
W-2 SurePrep 90-99%
1099 series SurePrep 85-99%
K-1 SurePrep 70-95%
1098 series SurePrep 90-99%
Bank statements Internal AI 60-85%
Brokerage statements SurePrep + AI 70-90%
ID documents Persona 80-99%
Other Internal AI 50-80%

7. E-Filing and Rejection Handling Flow

Detailed process for e-file transmission and rejection resolution.

7.1 Process Flow Diagram

flowchart TB
    subgraph PREFLIGHT["1. Pre-Filing Checks"]
        A[Return Approved] --> B[Verify 8879 Signed]
        B --> C{Signed?}
        C -->|No| D[Send Signature Reminder]
        D --> C
        C -->|Yes| E[Validate Return Data]
        E --> F[Check Required Fields]
        F --> G{Valid?}
        G -->|No| H[Fix Validation Errors]
        H --> E
        G -->|Yes| I[Queue for Transmission]
    end

    subgraph TRANSMIT["2. Transmission"]
        I --> J[Select Transmitter]
        J --> K[Format for MeF]
        K --> L[Transmit Federal]
        L --> M{Success?}
        M -->|No| N{Retry Count < 3?}
        N -->|Yes| O[Wait and Retry]
        O --> L
        N -->|No| P[Alert Staff]
        M -->|Yes| Q{State Returns?}
        Q -->|Yes| R[Transmit Each State]
        R --> S[Store All Submission IDs]
        Q -->|No| S
    end

    subgraph MONITOR["3. Status Monitoring"]
        S --> T[Start Polling Job]
        T --> U[Query IRS Status]
        U --> V{Status?}
        V -->|Pending| W[Wait 6 Hours]
        W --> U
        V -->|Accepted| X[Process Acceptance]
        V -->|Rejected| Y[Process Rejection]
        V -->|No Response 48hr| Z[Alert Staff - Stuck]
        Z --> AA[Manual Investigation]
        AA --> U
    end

    subgraph ACCEPT["4. Acceptance Flow"]
        X --> AB[Store Confirmation Number]
        AB --> AC[Update Return Status]
        AC --> AD[Create Audit Record]
        AD --> AE[Send Client Email]
        AE --> AF[Upload to SmartVault]
        AF --> AG[End - Accepted]
    end

    subgraph REJECT["5. Rejection Flow"]
        Y --> AH[Parse Error Codes]
        AH --> AI[Categorize Rejection]
        AI --> AJ{Category?}

        AJ -->|Technical| AK[Identify Fix]
        AK --> AL{Auto-Fixable?}
        AL -->|Yes| AM[Apply Fix]
        AM --> I
        AL -->|No| AN[Assign to Preparer]

        AJ -->|Data Mismatch| AN
        AN --> AO[Preparer Reviews]
        AO --> AP{Need Client Info?}
        AP -->|Yes| AQ[Send Question to Client]
        AQ --> AR[Client Responds]
        AR --> AS[Apply Correction]
        AP -->|No| AS
        AS --> I

        AJ -->|Duplicate| AT[Flag for Fraud Review]
        AT --> AU[EA/CPA Reviews]
        AU --> AV{Legitimate?}
        AV -->|Yes| AO
        AV -->|No| AW[Document Fraud Case]
        AW --> AX[Contact Client]
        AX --> AY[Close Case]
        AY --> AZ[End - Fraud]
    end

7.2 Rejection Categories and Handling

Category Example Codes Auto-Fix? Resolution Path
Technical SEIC-F1040-535 Often Fix format, resubmit
Data Mismatch IND-031 (SSN) No Verify with client
Missing Info FPYMT-F1040-905 Sometimes Add missing data
Duplicate R0000-902 No Fraud investigation
Fraud Indicator Various No EA/CPA escalation

7.3 Polling Schedule

Period Frequency Rationale
First 24 hours Every 2 hours Quick initial response
24-48 hours Every 6 hours Standard monitoring
48+ hours Alert staff Unusual delay
Tax season peak Every 4 hours Higher volume

8. Client Onboarding Flow

New client registration through first document upload.

8.1 Process Flow Diagram

flowchart TB
    subgraph INITIAL["1. Initial Contact"]
        A[New Client Inquiry] --> B[Collect Basic Info]
        B --> C[Create Prospect Record]
        C --> D[Run Conflict Check]
        D --> E{Conflict?}
        E -->|Yes| F[Review Conflict]
        F --> G{Proceed?}
        G -->|No| H[Decline Engagement]
        H --> Z1[End - Declined]
        G -->|Yes| I[Document Conflict Waiver]
        E -->|No| J[No Conflict Found]
        I --> J
    end

    subgraph ENGAGE["2. Engagement"]
        J --> K[Select Engagement Template]
        K --> L[Generate Engagement Letter]
        L --> M[Generate Form 7216 if Needed]
        M --> N[Create Signature Package]
        N --> O[Send via Google Workspace]
        O --> P{Signed?}
        P -->|No| Q[Send Reminder - Day 3]
        Q --> R{Signed?}
        R -->|No| S[Send Reminder - Day 7]
        S --> T{Signed?}
        T -->|No| U[Call Client]
        U --> P
        R -->|Yes| V[Store Signed Documents]
        T -->|Yes| V
        P -->|Yes| V
    end

    subgraph VERIFY["3. Identity Verification"]
        V --> W[Initiate Verification]
        W --> X{New Client?}
        X -->|Yes| Y[Tier 2 Verification]
        X -->|No| Z[Tier 1 Verification]
        Z --> AA{Passed?}
        AA -->|Yes| AB[Verification Complete]
        AA -->|No| Y
        Y --> AC{Passed?}
        AC -->|Yes| AB
        AC -->|No| AD[Offer Tier 3 Options]
        AD --> AE[Client Chooses Method]
        AE --> AF[Complete Tier 3]
        AF --> AG{Passed?}
        AG -->|Yes| AB
        AG -->|No| AH[Decline - Cannot Verify]
        AH --> Z2[End - Verification Failed]
    end

    subgraph SETUP["4. Account Setup"]
        AB --> AI[Convert Prospect to Client]
        AI --> AJ[Assign Account Number]
        AJ --> AK[Create SmartVault Structure]
        AK --> AL[Create Tax Return Record]
        AL --> AM[Generate Document Checklist]
        AM --> AN[Send Welcome Package]
    end

    subgraph COLLECT["5. Initial Collection"]
        AN --> AO[Client Receives Instructions]
        AO --> AP[Client Uploads First Document]
        AP --> AQ[Process Document]
        AQ --> AR[Update Progress]
        AR --> AS[Send Confirmation]
        AS --> AT[End - Onboarding Complete]
    end

8.2 Onboarding Timeline

Step Target Time Escalation
Initial contact Day 0 -
Engagement sent Day 0 -
First signature reminder Day 3 -
Second signature reminder Day 7 -
Phone follow-up Day 10 -
Engagement timeout Day 14 Close prospect
Identity verification Same day Tier escalation
Welcome package After verification -
First document Day 1-7 Missing doc reminder

8.3 SmartVault Folder Structure

/Clients/{ClientName}/
├── Tax Year {year}/
│   ├── Source Documents/
│   │   ├── W-2/
│   │   ├── 1099/
│   │   ├── K-1/
│   │   ├── Other Income/
│   │   ├── Deductions/
│   │   └── Other/
│   ├── Final Returns/
│   │   ├── Federal/
│   │   └── State/
│   ├── Engagement/
│   └── Correspondence/
└── Permanent/
    ├── ID Documents/
    └── Prior Returns/

Appendix: Progress Percentage by State

Workflow State Progress % Criteria
Intake 5% Return created
DocumentsPending 10% + (docs_received/docs_expected × 20%) Based on checklist
PendingClientResponse Previous + 5% Waiting for client
ReadyForPrep 35% All docs received
AIAnalysis 40% AI processing
InPrep 50% Active preparation
NeedsReview 50% Exception handling
ReadyForReview 70% Prep complete
InReview 75% Under review
RevisionsNeeded 60% Revisions requested
Approved 82% Review passed
PendingFinalQA 85% Overnight AI QA
PendingSignature 90% Awaiting signature
ReadyToFile 95% Ready to transmit
Filed 97% Transmitted
Accepted 100% IRS accepted
Rejected 50% Needs correction
Complete 100% All done

Last updated: December 2025

Document History: | Version | Date | Changes | |---------|------|---------| | 1.1 | 2025-12-25 | Added PendingFinalQA state for FUT-002 tiered validation. Cross-referenced with AI_DELEGATION_STRATEGY.md. | | 1.0 | 2024-12 | Initial version |