V1 Back-Office AI Companion Requirements¶

Version: 1.1 Date: 2025-12-28 Status: Draft

Executive Summary¶

V1 deploys Tax Practice AI as a back-office companion tool for Tax Season 2025. Staff use the AI analysis capabilities alongside existing workflows without disrupting client-facing processes.

Philosophy¶

Augment, don't replace - Enhances existing workflow, doesn't change it
Cloud-connected with graceful fallback - Full cloud architecture, but works offline for AI features
Zero client disruption - Clients continue using SmartVault and existing processes
Immediate value - Catches issues faster, automates research, generates worksheets

1. Deployment Model¶

1.1 What Changes¶

Component	V1 Behavior
Staff App	Deployed and used daily by preparers/reviewers
AI Analysis	Fully operational via Anthropic API
Document Storage	S3 (primary) with local fallback messaging
Client Records	Created in our system, linked to legacy account numbers
Export	Worksheets with annotations, sources, and analysis

1.2 What Stays The Same¶

Component	Existing Behavior
Client Portal	SmartVault (clients upload there)
Tax Preparation	UltraTax CS (actual return prep)
E-Filing	Via UltraTax (no change)
Client Communication	Existing email/phone processes
Source of Truth	Legacy system remains authoritative

1.3 Integration Points¶

┌─────────────────────────────────────────────────────────────────┐
│                     V1 COMPANION ARCHITECTURE                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐    │
│   │  SmartVault │      │  UltraTax   │      │   Legacy    │    │
│   │  (uploads)  │      │  (prep)     │      │   System    │    │
│   └──────┬──────┘      └─────────────┘      └──────┬──────┘    │
│          │                                         │            │
│          │ Manual download                         │ Account #  │
│          │ or drag-drop                           │            │
│          ▼                                         ▼            │
│   ┌─────────────────────────────────────────────────────┐      │
│   │              TAX PRACTICE AI (V1)                    │      │
│   │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │      │
│   │  │   Client    │  │  Document   │  │     AI      │  │      │
│   │  │   Records   │  │   Upload    │  │  Analysis   │  │      │
│   │  └─────────────┘  └─────────────┘  └─────────────┘  │      │
│   │                          │                          │      │
│   │                          ▼                          │      │
│   │                  ┌─────────────┐                    │      │
│   │                  │  Worksheet  │                    │      │
│   │                  │   Export    │                    │      │
│   │                  └─────────────┘                    │      │
│   └─────────────────────────────────────────────────────┘      │
│                              │                                  │
│                              ▼                                  │
│                     ┌─────────────┐                             │
│                     │    AWS      │                             │
│                     │  (S3, RDS)  │                             │
│                     └─────────────┘                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2. Client Management¶

2.1 Client Creation¶

Staff can create a client record in two ways:

New Client - Enter nothing, system generates new account number
Link to Legacy - Enter existing account number from legacy system

2.2 Account Numbering¶

Field	Description
account_number	Unique identifier for the client
legacy_account_number	Optional reference to existing system
Format	Prefix 'A' + numeric (e.g., A10001) - pending client confirmation

Configurable settings: - account_number_prefix: Default 'A' - account_number_start: Starting number (e.g., 10001) - account_number_format: Pattern for generation

2.3 Minimal Client Fields (V1)¶

Field	Required	Description
account_number	Auto	System-generated or entered
legacy_account_number	No	Link to existing system
display_name	Yes	Client name for display
tax_year	Yes	Current tax year being worked
notes	No	Free-form notes

Not required in V1: Full address, SSN, contact details (these exist in legacy system)

3. Document Upload¶

3.1 Upload Methods¶

Method	Description
Drag and Drop	Drag file(s) directly into the viewer
File Browser	Click to browse and select files
Folder Import	Point to local folder, import all documents

3.2 Supported Document Types¶

Category	File Types
Tax Documents	W-2, 1099 series, 1098 series, K-1
Financial	Bank statements (PDF), investment statements
Receipts	Scanned receipts, expense documentation
Data Files	CSV transaction exports
Prior Returns	Prior year tax return PDFs
Other	Any PDF, image (PNG, JPG), or data file

3.3 Document Processing Pipeline¶

Upload → Classification → Extraction → AI Analysis → Ready for Review

Upload - File received, stored in S3 (or local fallback)
Classification - AI identifies document type
Extraction - Pull structured data (amounts, dates, names)
Analysis - Cross-reference, anomaly detection, prior year comparison
Ready - Available in review interface with AI insights

3.4 S3 Connectivity Fallback¶

When S3 is unavailable:

┌─────────────────────────────────────────────────────────────────┐
│  ⚠️  Cloud Storage Unavailable                                  │
│                                                                  │
│  AI Companion features are still available.                     │
│                                                                  │
│  Documents cannot be stored in the cloud at this time.          │
│  Please keep files in your existing system as the source        │
│  of truth until connectivity is restored.                       │
│                                                                  │
│  [Continue with Local Analysis]    [Retry Connection]           │
└─────────────────────────────────────────────────────────────────┘

Behavior: - AI analysis works (documents sent directly to Anthropic) - Documents NOT persisted to S3 - User warned to maintain files in legacy system - Results can still be exported to worksheet

4. AI Analysis Features¶

4.1 Core Capabilities¶

Feature	Description
Document Classification	Automatically identify W-2, 1099, bank statement, etc.
Data Extraction	Pull amounts, dates, names, account numbers
Prior Year Comparison	Compare to prior year return data
Missing Document Detection	Identify expected but missing documents
Anomaly Detection	Flag unusual items before reviewer looks
Q&A Assistant	Ask questions during review

4.2 Q&A Examples¶

"Compare this W-2 to last year"
"What documents are we still missing?"
"Summarize the investment income"
"Are there any red flags I should look at?"
"What's the total charitable contributions?"

4.3 Analysis Dashboard¶

Section	Content
Summary	Client overview, tax year, document count
Documents	List of uploaded docs with classification
Insights	AI-generated observations and flags
Missing Items	Documents expected but not received
Prior Year Delta	Key differences from prior year
Q&A History	Questions asked and responses

5. Worksheet Export¶

5.1 Export Requirements¶

The worksheet export is a critical deliverable. It must include:

Section	Description
Client Header	Account number, name, tax year
Document Inventory	All documents received with classification
Extracted Data	Structured data pulled from documents
Annotations	Preparer notes and observations
Source References	Citations linking analysis to source documents
Detailed Analysis	AI-generated analysis with findings
Questions/Flags	Items requiring attention
Prior Year Comparison	Key changes from prior year

5.2 Source Citations¶

Every piece of analysis must reference its source:

Income Analysis:
- W-2 wages: $85,432.00 [Source: W-2_Employer_ABC.pdf, Box 1]
- Interest income: $1,234.56 [Source: 1099-INT_Bank_XYZ.pdf, Box 1]
- Dividend income: $567.89 [Source: 1099-DIV_Broker_123.pdf, Box 1a]

Note: Interest income increased 45% from prior year ($851.00 → $1,234.56)
      [Source: Prior Year Return, Schedule B]

5.3 Export Formats¶

Format	Use Case
PDF	Print-ready worksheet with formatting
Excel	Editable spreadsheet with data tables
Markdown	Text-based for easy copying

5.4 Annotations¶

Staff can add annotations during review:

# Annotation types
- NOTE: General observation
- FLAG: Requires attention
- QUESTION: Need to ask client
- VERIFIED: Confirmed correct
- OVERRIDE: Manual correction with reason

Each annotation is timestamped and attributed to the user.

6. User Interface Changes¶

6.1 Staff App Modifications¶

Change	Description
Client Quick Create	Simplified form: name + optional legacy account
Drag-Drop Zone	Large drop target in document viewer
Folder Import	Button to select local folder
Offline Banner	Shows when S3 unavailable
Export Button	Generate worksheet with current analysis
Annotation Tools	Add notes, flags, questions to documents

6.2 New Screens¶

Screen	Purpose
Client Quick Entry	Fast client creation for V1
Document Drop Zone	Upload area with drag-drop
Analysis Dashboard	AI insights and findings
Worksheet Preview	Preview before export
Export Options	Select format and content

Dashboard → Quick Create Client → Upload Documents → AI Analysis → Export Worksheet
                    ↓                    ↓                ↓
              Enter legacy #      Drag-drop or      Ask questions
              or generate new     browse folder     Add annotations

7. Data Model Changes¶

7.1 New Fields¶

client table:

-- New columns for V1
legacy_account_number VARCHAR(50),     -- Reference to existing system
account_number_prefix VARCHAR(10),     -- 'A' by default
v1_quick_entry BOOLEAN DEFAULT TRUE,   -- Created via quick entry

document table:

-- New columns for V1
local_fallback BOOLEAN DEFAULT FALSE,  -- True if S3 was unavailable
source_folder VARCHAR(500),            -- Original folder path if folder import

New table: annotation

CREATE TABLE annotation (
    id UUID PRIMARY KEY,
    document_id UUID REFERENCES document(id),
    client_id UUID REFERENCES client(id),
    user_id UUID REFERENCES users(id),
    annotation_type VARCHAR(20),        -- NOTE, FLAG, QUESTION, VERIFIED, OVERRIDE
    content TEXT,
    source_reference TEXT,              -- Page/location in document
    created_at TIMESTAMPTZ,
    updated_at TIMESTAMPTZ
);

New table: worksheet_export

CREATE TABLE worksheet_export (
    id UUID PRIMARY KEY,
    client_id UUID REFERENCES client(id),
    tax_year INTEGER,
    export_format VARCHAR(20),          -- PDF, EXCEL, MARKDOWN
    content JSONB,                       -- Structured export data
    exported_by UUID REFERENCES users(id),
    exported_at TIMESTAMPTZ,
    s3_key VARCHAR(500)                 -- Location of exported file
);

7.2 Configuration¶

config.yaml additions:

# =============================================================================
# V1 COMPANION SETTINGS
# =============================================================================
v1_companion:
  # account_number_prefix: Prefix for generated account numbers
  # Default: 'A' (pending client confirmation)
  account_number_prefix: ${ACCOUNT_PREFIX:-A}

  # account_number_start: Starting number for new accounts
  account_number_start: ${ACCOUNT_START:-10001}

  # enable_local_fallback: Allow AI analysis when S3 unavailable
  enable_local_fallback: true

  # export_formats: Available worksheet export formats
  export_formats:
    - pdf
    - excel
    - markdown

  # require_source_citations: Enforce citations in analysis
  require_source_citations: true

8. API Endpoints¶

8.1 New Endpoints¶

Method	Endpoint	Description
POST	/v1/clients/quick	Quick client creation
POST	/v1/documents/upload	Upload with drag-drop/browse
POST	/v1/documents/folder-import	Import from local folder
GET	/v1/clients/{id}/analysis	Get AI analysis dashboard
POST	/v1/clients/{id}/annotations	Add annotation
GET	/v1/clients/{id}/worksheet	Generate worksheet
POST	/v1/clients/{id}/worksheet/export	Export to format
GET	/v1/system/connectivity	Check S3/cloud status

8.2 Quick Client Create¶

Request:

{
  "display_name": "John Smith",
  "legacy_account_number": "12345",  // Optional
  "tax_year": 2024,
  "notes": "Referred by Jane Doe"    // Optional
}

Response:

{
  "id": "uuid",
  "account_number": "A10001",
  "legacy_account_number": "12345",
  "display_name": "John Smith",
  "tax_year": 2024,
  "created_at": "2024-12-24T10:00:00Z"
}

8.3 Worksheet Export¶