Skip to content

Tax Practice AI - Completed Items

Historical record of completed phases, resolved decisions, and finished work

Document Purpose
backlog.md Active priorities
TECH_DEBT.md Technical debt tracking
ROADMAP.md Future features
DESIGN_DECISIONS.md Architecture decisions
index.md Master navigation

Client Decisions (Resolved)

TAX-001: Tax Software Selection

Status: Resolved (2024-12-23) Decision: UltraTax CS (Thomson Reuters) Integration: Via SurePrep CS Connect bridge (UltraTax has no direct API)

TAX-002: Volume Projections

Status: Resolved (2024-12-23) Decision: ~1,000 returns/year with 30% annual growth expectation

Timeframe Returns per Year
Year 1 1,000
Year 2 1,300
Year 3 1,700
Year 5 2,850

Note: Growth may accelerate due to system efficiency gains.

TAX-003: Entity Type Mix

Status: Resolved (2024-12-23) Decision: Equal priority for individuals and businesses. Business clients are primarily small businesses (advanced individuals). No differentiation needed in V1.

TAX-004: State Coverage

Status: Resolved (2024-12-23) Decision: Florida + surrounding states (GA, AL, SC, NC) initially. Design for all 50 states from the start - full coverage expected soon.

Phase 0: Data Migration (Complete)

Data migration tools completed and ready for pre-launch use.

MIG-001: Client Data Import Tool

Status: COMPLETE Priority: P0 (Pre-Launch Blocker)

  • CLI tool: tax-migrate clients <file>
  • CSV/Excel parsing with column mapping
  • Duplicate detection and handling
  • Account number generation for imports
  • Dry-run mode for validation
  • Import summary report
  • Audit logging

Files: - scripts/tax_migrate.py - CLI entry point - src/migration/client_importer.py - Main import logic - src/migration/column_mapper.py - Flexible column mapping - src/migration/duplicate_detector.py - Duplicate detection - src/migration/import_report.py - Report generation - tests/unit/test_migration_column_mapper.py - Unit tests (16 tests)

MIG-002: Bulk Document Import Tool

Status: COMPLETE Priority: P0 (Pre-Launch Blocker)

  • CLI tool: tax-migrate documents <folder> (with --preview mode)
  • Folder structure pattern matching (client-name-first, account-first, year-first)
  • Document classification by filename (W-2, 1099, 1098, K-1, identity docs, etc.)
  • Client matching with fuzzy name support (configurable threshold)
  • Malware scanning integration (placeholder for ClamAV)
  • Unmatched document quarantine (--quarantine-dir option)
  • Import report with match statistics

Files: - src/migration/document_classifier.py - Document type classification - src/migration/client_matcher.py - Client matching with fuzzy support - src/migration/document_importer.py - Main import logic - tests/unit/test_migration_document_classifier.py - Unit tests (22 tests)

MIG-003: Historical Return Data Import

Status: COMPLETE Priority: P0 (Pre-Launch Blocker)

  • CLI tool: tax-migrate history <file> (with --preview, --dry-run modes)
  • UltraTax export format support
  • Generic CSV format support
  • Prior year AGI import and client update
  • Filing status normalization
  • Refund/balance due import
  • Return history record creation
  • Client matching by external_id and SSN-4

Files: - src/migration/history_importer.py - History import logic - tests/unit/test_migration_history_importer.py - Unit tests (27 tests)

MIG-004: Migration Validation & Rollback

Status: COMPLETE Priority: P1

  • Migration summary report generation
  • Source vs imported count comparison
  • Error and warning listing
  • Sample client report for spot-checking
  • Rollback preview
  • Rollback CLI: tax-migrate rollback <batch-id>
  • List recent migration batches: tax-migrate rollback --list
  • Validate batch: tax-migrate rollback <batch-id> --validate
  • Generate report: tax-migrate rollback <batch-id> --report

Files: - src/migration/migration_validator.py - Validation and rollback logic - tests/unit/test_migration_validator.py - Unit tests (16 tests)

Phase 1: Foundation (Complete)

FOUND-001: Project Structure Setup

Status: Complete Priority: P0

  • Create ARCHITECTURE.md
  • Create CLAUDE.md
  • Create RUNBOOK.md
  • Create backlog.md
  • Create src/ directory structure
  • Create config.yaml with commented parameters
  • Set up requirements.txt with core dependencies
  • Create .env.example template

FOUND-002: Service Centralization Framework

Status: Complete Priority: P0

  • Create src/services/base_service.py
  • Create src/services/init.py (ServiceRegistry)
  • Create src/config/settings.py

FOUND-004: Aurora Service Implementation

Status: Complete Priority: P1

  • Create src/services/aurora_service.py
  • Implement connection pooling
  • Add transaction support
  • Add health check method
  • Add database error mapping (ConflictError, ValidationError, etc.)

Phases 2-11: Implementation Sequences (Complete)

Sequence 2: Client Identity (Complete)

  • S2-001: Client Self-Registration
  • S2-002: Identity Verification with Persona
  • S2-003: Returning Client Authentication
  • S2-004: Profile Management

Sequence 3: Engagement (Complete)

  • S3-001: Engagement Letter Generation
  • S3-002: E-Signature via Google Docs
  • S3-003: Form 7216 Consent Management

Sequence 4: Document Management (Complete)

  • S4-001: Document Upload via Portal
  • S4-002: Document Upload via Email
  • S4-003: Malware Scanning
  • S4-004: Document Classification and Extraction
  • S4-005: SmartVault Integration
  • S4-006: SurePrep Integration
  • S4-007: Document Checklist Management
  • S4-008: Manual Extraction Correction

Sequence 5: AI Analysis (Complete)

  • S5-001: Preliminary Return Analysis
  • S5-002: Prior Year Comparison
  • S5-003: Missing Document Detection
  • S5-004: AI-Powered Q&A
  • S5-005: Extraction Corrections
  • S5-006: Analysis Dashboard

Sequence 6: Tax Preparation Workflow (Complete)

  • S6-001: Workflow State Machine
  • S6-002: Preparer Assignment
  • S6-003: Reviewer Assignment
  • S6-004: Progress Tracking
  • S6-005: Dashboard Views
  • S6-006: Time Tracking
  • S6-007: Priority Management
  • S6-008: Batch Operations
  • S6-009: Analytics

Sequence 7: Preparer & Reviewer Interface (Complete)

  • S7-001: Interactive Review Interface
  • S7-002: AI Q&A Assistant
  • S7-003: Change Tracking
  • S7-004: Final Review Package

Sequence 8: Client Communication (Complete)

  • S8-001: Secure Portal Messaging
  • S8-002: Email Notifications
  • S8-003: SMS Notifications
  • S8-004: Callback Scheduling
  • S8-005: Notification Preferences

Sequence 9: Client Delivery (Complete)

  • S9-001: Tax Package Generation
  • S9-002: Google Workspace Signature Integration
  • S9-003: Payment Authorization

Sequence 10: E-Filing Status Tracking (Complete)

  • S10-001: E-File Status Monitoring
  • S10-002: Mark Return Ready for Filing
  • S10-003: Filing Ready Check
  • S10-004: Rejection Management

Sequence 11: Billing & Payments (Complete)

  • S11-001: Stripe Service Implementation
  • S11-002: Invoice Generation
  • S11-003: Payment Collection
  • S11-004: Payment Reminders

Sequence 12: Estimated Tax Management (Complete - 3 of 4 stories)

  • S12-001: Estimated Tax Calculation
  • S12-002: Voucher Generation
  • S12-003: Calendar Event Generation
  • S12-004: Estimated Tax Reminders (DEFERRED - liability risk)

S12-004 Deferral Note: By sending estimated tax reminders, the firm implies responsibility for notifying clients. When emails or SMS are missed (spam filters, wrong number, etc.), clients blame the firm for their missed payments and penalties. This inappropriately shifts liability. Clients should use calendar events (S12-003) instead.

Sequence 13: AI Chat (Complete)

  • S13-001: Chat Domain & Repository
  • S13-002: Chat Service with CLI/API Modes
  • S13-003: Chat API Routes
  • S13-004: Staff-App Chat UI

Features: - Tax-focused system prompt with off-topic redirection - Single-client scope enforcement (no cross-client queries) - CLI mode for local dev (uses developer's Claude subscription) - API mode for production (AWS Bedrock) - Extended context building (client, return, documents, prior year) - Floating drawer UI in staff-app ClientDetailPage - Token/cost tracking per session

Implementation Files: - Domain: src/domain/chat.py - Repository: src/repositories/chat_repository.py - Service: src/services/chat_service.py - API: src/api/routes/chat.py - Schemas: src/api/schemas/chat_schemas.py - Frontend: frontend/apps/staff-app/src/components/chat/ - Hook: frontend/apps/staff-app/src/hooks/useChat.ts

Documentation Milestones (Complete)

DOC-001: Pre-Implementation Documentation

Completed: 2024-12-23

  • DATABASE_SCHEMA.sql - Complete 35-table schema with 50 enums
  • DATA_MODEL.md - Logical data model with ER diagrams
  • API_SPECIFICATION.md - Full REST API contract
  • INTEGRATION_CONTRACTS.md - External service integrations
  • SECURITY_DESIGN.md - Security architecture and controls
  • PROCESS_FLOWS.md - State machines and workflows
  • USER_STORIES.md - 82 prioritized user stories (77 MVP, 5 post-MVP)

DOC-002: Documentation Reconciliation

Completed: 2024-12-23

All pre-implementation specifications validated and reconciled: - Enum values aligned across all documents - Missing endpoints added to API specification - ER diagram updated with all 35 entities - Webhook handlers aligned with integration contracts - Cross-references added between documents

Technical Debt Completed

TD-002: CI/CD Pipeline

Completed: 2024-12-24 - GitHub Actions workflow with lint, unit, integration, and e2e tests

TD-003: Testing Framework

Completed: 2024-12-24 - Full test pyramid: 1,522 tests (85% unit, 12% integration, 3% e2e)

TD-005: Test Data Generator

Completed: 2024-12-26 - 7 user personas with complete document sets - PDF/image generation with quality variations

TD-014: Fix Unit Test Signature Mismatches

Completed: 2024-12-29 - Fixed MetadataService.assign_batch_to_client() test calls

TD-015: Align bootstrap.py Schema with Production

Completed: 2024-12-29 - Schema tables aligned, integration tests: 82 → 238 passed

TD-016: Fix Integration Test Isolation

Completed: 2024-12-30 - Email domain conventions, fixture isolation, 238 tests passing

TD-017: Refactor bootstrap.py to Separate DDL from Seeding

Completed: 2024-12-30 - Removed 360+ lines of embedded DDL - Table names parsed dynamically from DATABASE_SCHEMA.sql - Added table groups for selective truncation (--exclude, --only) - Added --schema flag to apply DATABASE_SCHEMA.sql - Updated RUNBOOK.md section 5.1

TD-018: Remove Hardcoded Config and Fallback Paths

Completed: 2024-12-30 GitHub Issue: #4

Changes: - Deleted scripts/local_api.py (1,735 lines removed) - Local dev now uses same src/api/main.py as production - Eliminates forked codebase maintenance burden - Updated scripts/bootstrap.py to use get_config() - DB connection config from centralized config module - S3 config (endpoint_url, bucket) from config - Container name configurable via POSTGRES_CONTAINER env var - Updated scripts/seed_demo_data.py to use get_config() - Updated tests/integration/test_readiness.py to use get_config() - Updated repositories to use config for bucket names - src/repositories/document_repository.py - src/repositories/pending_document_repository.py - Updated documentation - ARCHITECTURE.md (removed local_api.py references) - TEST_PROTOCOL.md (API startup commands) - TECH_DEBT.md (marked related audit items N/A)

Test Results: - bootstrap.py --reset: ✅ Works - API startup (src/api/main.py): ✅ Works - Readiness tests: 9/10 pass - Config module loading: ✅ Works

Known Issue (Pre-existing, Unrelated to TD-018): - test_chat_session_creation fails with 500 error - Chat session endpoint returns internal server error - Not a regression from TD-018 (chat functionality issue)

Net Result: -1,640 lines (1,835 deleted, 195 added)

Test Coverage Milestones

Milestone Date Tests
Initial test pyramid 2024-12-24 187
S3 complete 2024-12-24 207
S4 complete 2024-12-24 495
S2-S11 complete 2024-12-24 1,522
Current 2025-12-28 1,820+

Last updated: 2025-12-30