V1 Back-Office AI Companion - Use Cases¶
Version: 1.1 Date: 2025-12-28 Related: V1_COMPANION_REQUIREMENTS.md
Overview¶
This document details the use cases for the V1 Back-Office AI Companion deployment. These use cases focus on staff-facing functionality that augments the existing tax preparation workflow.
Actors¶
| Actor | Description |
|---|---|
| Preparer | Tax preparer who processes returns |
| Reviewer | Senior preparer who reviews completed work |
| Admin | Office administrator (manages clients, settings) |
| System | Automated system processes |
UC-V1-001: Quick Client Creation¶
Actor: Preparer, Admin
Preconditions: - User is authenticated in Staff App - User has permission to create clients
Main Flow: 1. User navigates to "New Client" (quick entry mode) 2. System displays minimal entry form: - Display name (required) - Tax year (required, defaults to current) - Legacy account number (optional) - Notes (optional) 3. User enters client name 4. User optionally enters legacy account number from existing system 5. User clicks "Create Client" 6. System generates new account number (prefix 'A' + sequence) 7. System creates client record 8. System redirects to document upload screen
Alternate Flow - Legacy Account Entered: - 4a. User enters existing account number (e.g., "12345") - 4b. System stores as legacy_account_number - 4c. System still generates new account_number (e.g., "A10001") - 4d. Both numbers are displayed for reference
Postconditions: - New client record exists with unique account number - Client is ready for document upload - Audit log records creation
UC-V1-002: Drag-and-Drop Document Upload¶
Actor: Preparer, Reviewer
Preconditions: - Client record exists - User is viewing client's document area
Main Flow: 1. User opens client record 2. System displays document drop zone with message: "Drag files here or click to browse" 3. User drags one or more files from desktop/folder 4. Files land in drop zone 5. System shows upload progress for each file 6. For each file: a. System uploads to S3 b. System triggers classification c. System triggers extraction 7. System displays uploaded documents with classifications 8. System updates document list in real-time
Alternate Flow - Click to Browse: - 3a. User clicks drop zone - 3b. System opens file browser dialog - 3c. User selects one or more files - 3d. Continue from step 5
Alternate Flow - S3 Unavailable: - 6a. S3 upload fails - 6b. System displays warning banner: "Cloud Storage Unavailable. AI Companion features are still available. Documents cannot be stored at this time. Keep files in your existing system as the source of truth." - 6c. System stores document in local/temp storage for AI analysis only - 6d. Document marked with local_fallback = true - 6e. AI analysis proceeds normally
Postconditions: - Documents stored in S3 (or local fallback) - Classification and extraction initiated - Document appears in client's document list
UC-V1-003: Folder Import¶
Actor: Preparer, Admin
Preconditions: - Client record exists - User has local folder with documents
Main Flow: 1. User clicks "Import Folder" button 2. System opens folder browser dialog 3. User selects a folder containing documents 4. System scans folder recursively for supported file types 5. System displays preview: - Total files found: X - Supported: Y - Unsupported: Z (with list) 6. User confirms import 7. System uploads each file: - Progress bar shows overall progress - Each file classified and extracted 8. System displays summary: - Uploaded: Y - Skipped (unsupported): Z - Failed: N (with error details)
Alternate Flow - Empty Folder: - 4a. No supported files found - 4b. System displays message: "No supported documents found in folder" - 4c. User can select different folder or cancel
Alternate Flow - Mixed Results: - 8a. Some files fail (unsupported format, corrupt, etc.) - 8b. System shows success count and failure details - 8c. User can retry failed files or proceed
Postconditions: - All supported documents uploaded - Each document classified and extraction initiated - source_folder metadata preserved for traceability
UC-V1-004: View AI Analysis Dashboard¶
Actor: Preparer, Reviewer
Preconditions: - Client has uploaded documents - At least one document has been processed
Main Flow: 1. User opens client record 2. User clicks "Analysis" tab 3. System displays AI Analysis Dashboard:
Summary Section: - Client: [Name] (Account: [Number]) - Tax Year: 2024 - Documents: X uploaded, Y processed
Documents Section: - Table of documents with classification, status, key values
Insights Section: - AI-generated observations - Anomalies detected - Items requiring attention
Missing Documents Section: - Expected documents not yet received - Based on document types and prior year
Prior Year Comparison Section: - Key changes from prior year (if prior data available) - Income delta, deduction changes, etc.
- User can click any section to expand details
- User can click any document to view it with extracted data
Alternate Flow - No Documents: - 3a. No documents uploaded yet - 3b. System displays: "No documents uploaded. Upload documents to see AI analysis."
Alternate Flow - Processing In Progress: - 3a. Some documents still processing - 3b. System shows progress indicator - 3c. Dashboard updates as documents complete
Postconditions: - User has visibility into AI analysis - Can drill into any finding
UC-V1-005: Ask AI Question During Review¶
Actor: Preparer, Reviewer
Preconditions: - Client has processed documents - User is viewing Analysis Dashboard or document
Main Flow: 1. User clicks "Ask AI" button or types in Q&A input 2. System displays Q&A interface 3. User types question, e.g.: - "Compare W-2 wages to last year" - "What documents are we missing?" - "Summarize all 1099 income" - "Are there any red flags?" 4. System sends question to AI with document context 5. AI responds with: - Answer to question - Source citations for each claim - Relevant document references 6. Response appears in Q&A panel 7. User can ask follow-up questions 8. System maintains conversation context
Alternate Flow - No Relevant Documents: - 5a. Question refers to documents not uploaded - 5b. AI responds: "I don't see any [document type] in the uploaded documents. Please upload them to answer this question."
Postconditions: - Q&A history preserved for reference - Can be included in worksheet export
UC-V1-006: Add Annotation to Document¶
Actor: Preparer, Reviewer
Preconditions: - Document exists and is viewable - User has annotation permission
Main Flow: 1. User views document in document viewer 2. User clicks "Add Annotation" or selects text/area 3. System displays annotation form: - Type: [NOTE | FLAG | QUESTION | VERIFIED | OVERRIDE] - Content: [text area] - Location: [auto-filled based on selection] 4. User selects annotation type 5. User enters annotation content 6. User clicks "Save" 7. System saves annotation linked to document 8. Annotation marker appears on document 9. Annotation appears in document's annotation list
Annotation Types: - NOTE: General observation or reminder - FLAG: Requires attention or follow-up - QUESTION: Need to ask client about this - VERIFIED: Confirmed correct/reviewed - OVERRIDE: Manual correction with documented reason
Alternate Flow - Override with Value: - 4a. User selects OVERRIDE type - 4b. System requires additional fields: - Original value: [auto-filled from extraction] - Corrected value: [user enters] - Reason: [required explanation] - 4c. Override recorded with full audit trail
Postconditions: - Annotation saved with timestamp and user - Visible on document and in annotation list - Included in worksheet export
UC-V1-007: Generate Worksheet Preview¶
Actor: Preparer, Reviewer
Preconditions: - Client has processed documents - AI analysis complete
Main Flow: 1. User clicks "Generate Worksheet" 2. System compiles worksheet with:
Client Header: - Account Number, Legacy Account (if any) - Client Name - Tax Year - Prepared by / Date
Document Inventory: - All documents with classification - Date received - Key values extracted
Extracted Data Summary: - Income summary with sources - Deduction summary with sources - Other relevant data
Annotations: - All notes, flags, questions, overrides - Grouped by document
Source References: - Every value traced to source document - Format: [Value] [Source: Document.pdf, Page X, Field Y]
Detailed Analysis: - AI analysis narrative - Findings and observations - Prior year comparison (if available)
Open Items: - Flags requiring attention - Questions for client - Missing documents
- System displays worksheet preview
- User can scroll through preview
- User can click any source reference to view original document
Postconditions: - Worksheet preview displayed - Ready for export
UC-V1-008: Export Worksheet¶
Actor: Preparer, Reviewer
Preconditions: - Worksheet preview generated
Main Flow: 1. From worksheet preview, user clicks "Export" 2. System displays export options: - Format: [PDF | Excel | Markdown] - Include sections: - [x] Document Inventory - [x] Extracted Data - [x] Annotations - [x] AI Analysis - [x] Prior Year Comparison - [x] Source Citations - [x] Open Items 3. User selects format and sections 4. User clicks "Export" 5. System generates file: - PDF: Formatted document with headers, tables, citations - Excel: Multi-sheet workbook (one per section) - Markdown: Text file with formatting 6. System saves export to S3 (or offers download if S3 unavailable) 7. System offers download link
Alternate Flow - PDF with Signatures: - 2a. User selects PDF format - 2b. User checks "Include signature lines" - 2c. Generated PDF includes preparer/reviewer signature blocks
Alternate Flow - S3 Unavailable: - 6a. S3 upload fails - 6b. System triggers direct browser download - 6c. Warns user to save file locally
Postconditions: - Export file generated - Saved to S3 (or downloaded) - Export record logged
UC-V1-009: Check Cloud Connectivity¶
Actor: System, User
Preconditions: - User is using the application
Main Flow: 1. System periodically checks S3 connectivity (every 60 seconds) 2. If connected: - Status indicator shows green - All features available 3. If disconnected: - Status indicator shows yellow/red - Banner displays connectivity warning - AI features remain available - Upload/storage features show fallback message
User-Initiated Check: 1. User clicks connectivity indicator 2. System displays connectivity status: - S3: Connected / Disconnected (last check: X seconds ago) - Database: Connected / Disconnected - AI API: Connected / Disconnected 3. User can click "Retry Connection" 4. System attempts reconnection 5. Status updates accordingly
Postconditions: - User informed of connectivity status - Can continue work with degraded features
UC-V1-010: Prior Year Data Entry¶
Actor: Preparer, Admin
Preconditions: - Client record exists - Prior year return available (PDF or data)
Main Flow: 1. User opens client record 2. User clicks "Prior Year Data" tab 3. User can either: a. Upload prior year return PDF b. Manually enter key prior year values 4. If PDF uploaded: - System extracts key values via AI - Displays extracted values for verification - User confirms or corrects 5. If manual entry: - User enters: AGI, filing status, refund/balance, key income items 6. System saves prior year data 7. Prior year comparison now available in analysis
Alternate Flow - Multiple Prior Years: - 3a. User can add data for multiple prior years - 3b. System stores each year separately - 3c. Analysis can compare current to any prior year
Postconditions: - Prior year data stored for comparison - AI analysis can reference prior year
Use Case Summary¶
| ID | Name | Priority |
|---|---|---|
| UC-V1-001 | Quick Client Creation | Must Have |
| UC-V1-002 | Drag-and-Drop Document Upload | Must Have |
| UC-V1-003 | Folder Import | Must Have |
| UC-V1-004 | View AI Analysis Dashboard | Must Have |
| UC-V1-005 | Ask AI Question During Review | Must Have |
| UC-V1-006 | Add Annotation to Document | Must Have |
| UC-V1-007 | Generate Worksheet Preview | Must Have |
| UC-V1-008 | Export Worksheet | Must Have |
| UC-V1-009 | Check Cloud Connectivity | Must Have |
| UC-V1-010 | Prior Year Data Entry | Should Have |
Document History¶
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2024-12-24 | Claude | Initial V1 use cases |