Merge vision brief.

Fix remaining hardcoded EFSP urls.

Author: codestronger

docs/vision-eval-20250827.md

@@ -0,0 +1,107 @@
+# Status Check vs Vision
+Based on the current codebase, here’s where things stand relative to your MVP vision.
+
+## What’s in place
+
+- __EFSP integration basics__
+  - Auth/tokens in `efile/api/auth_views.py` (login/logout, Tyler token, Suffolk eFile auth).
+  - Filing CRUD in `efile/api/filing_views.py` (list/create/update/delete via Suffolk endpoints).
+  - Case lookup, payment accounts, profiles present in `auth_views.py` and related API views.
+
+- __Expert mode form flow__
+  - Expert form with cascading dropdowns/validation: `efile/views/expert_form.py`.
+  - Config-driven sections: `efile/api/config_views.py` delegates to `CaseFormAPIViews` for jurisdiction-aware JSON.
+
+- __YAML config system and merging__
+  - Loader: `efile/utils/config_loader.py`.
+  - Files: `efile/static/config/` and `efile/static/config/states/`.
+  - Docs: `efile/static/config/README.md`.
+
+- __Uploads and mapping to EFSP__
+  - `efile/views/upload.py` implements `create_filing()` (maps session → Suffolk payload) and `upload_documents()` (S3 → Suffolk document registration), plus mock/simple upload utilities.
+
+## Gaps vs Vision
+
+- __Filing Flow runner (recipe-driven)__: No generalized sequence/branch/validate engine or persisted recipes for curated flows.
+- __Form Blocks abstraction and UI__: No explicit Form Block schema/type library and reusable UI components.
+- __Guided Interview__: No dedicated runner/UI for linear/branching flows with instructions/progress.
+- __Mapping layer formalization__: Current logic in `transform_case_data_to_filing_payload()`; needs declarative, testable mapping per recipe.
+- __Review & Submit__: Missing human-readable review step before submission.
+- __Error surfaces__: No normalization/triage with actionable guidance/retries.
+- __Configuration management UX__: No admin UI for non-technical authoring/editing of Blocks/Flows.
+- __Tests__: Limited tests for flow engine, YAML court overrides, and EFSP interactions.
+
+## Recommended Next Steps (MVP-targeted)
+
+1. __Introduce a Filing Flow “recipe” format (JSON/YAML)__
+   - Minimal schema: metadata (`id`, `title`, `jurisdiction`), steps (Form Blocks), branching (`next_if`, `next_else`), validation, mapping.
+   - Store in `efile/static/flows/{jurisdiction}/...` (DB later).
+
+2. __Form Blocks library__
+   - Block types: `text`, `textarea`, `number`, `radio`, `dropdown`, `party_selector`, `file_upload`, `date`, `checkbox`.
+   - Reuse/standardize with `efile/static/config/base-case-types.yaml` and `states/*.yaml` for both expert and guided flows.
+
+3. __Flow runner backend__
+   - Module `efile/flow/runner.py`: load recipe, evaluate conditions, session storage, validations.
+   - API `efile/api/flow_views.py`:
+     - `GET /api/flows/{flow_id}` (metadata + first step)
+     - `POST /api/flows/{flow_id}/steps/{step_id}` (submit answers → next step)
+     - `GET /api/flows/{flow_id}/review` (summary)
+     - `POST /api/flows/{flow_id}/submit` (create filing + documents)
+
+4. __Guided Interview UI__
+   - Single-page shell: progress, step title, instructions, renderer, Next/Back, validations, save-to-session.
+   - Reuse `efile/static/js/*` patterns and JSON from `config_views.py`; add lightweight `flow.js` if needed.
+
+5. __Mapping layer__
+   - Move to `efile/flow/mapping.py`; recipe-aware mappings.
+   - `transform(flow_answers, case_context) -> filing_payload`; add unit tests (name change, eviction basic).
+
+6. __Review & Submit__
+   - `GET /api/flows/{id}/review` returns a structured summary for UI.
+   - Submit reuses `create_filing()` and document uploads when referenced by answers.
+
+7. __Error handling__
+   - Central EFSP error normalizer: categorize (auth/validation/upstream), guidance, retry suggestions.
+   - Integrate in `upload.py` and `filing_views.py`.
+
+8. __Tests__
+   - Flow runner branching/validation; config merging for courts (e.g., `cook:cd1` vs `cook:chd1` per `efile/static/config/README.md`); mapping integration tests.
+
+## Concrete Implementation Plan
+
+- __Backend__
+  - Create `efile/flow/`: `schemas.py` (dataclasses/Pydantic for Block/Step/Recipe), `runner.py`, `mapping.py`, (optional) `models.py` for persistence.
+  - API: `efile/api/flow_views.py`. Wire URLs/permissions. Store answers in session first; DB later.
+
+- __Frontend__
+  - Add `efile/static/js/flow-runner.js`: fetch recipe/step, render, post, navigate. Reuse CSS in `efile/static/css/`.
+
+- __Leverage existing pieces__
+  - Reuse dropdown endpoints and party types via `config_views.py` and Suffolk codes.
+  - Reuse S3 patterns from `upload.py`.
+
+## Open Questions
+
+- Recipes YAML (human-friendly) or JSON (browser-native)? Suggest YAML in repo + compile to JSON at runtime.
+- Attachments: embed file-upload blocks in steps now or upload at review step?
+- Initial guided flow: Illinois Name Change (best documented today)?
+
+## Proposed Short Milestones
+
+- __M1 (day 1-2)__: Schemas + runner skeleton (load/next/back), session storage, minimal API.
+- __M2 (day 3-4)__: Mapping layer + Review & Submit, integrate with `create_filing()`.
+- __M3 (day 5)__: Guided Interview UI MVP with 1 flow (Name Change).
+- __M4 (day 6)__: Tests (runner, mapping, config merging) + error normalization.
+
+## Current TODOs
+
+- Audit existing EFSP endpoints and config system, document gaps vs vision (in progress)
+- Design Form Blocks schema
+- Implement Filing Flow runner backend
+- Build Guided Interview UI
+- Implement mapping layer
+- Add Review & Submit step
+- Improve error handling
+- Add attachments support
+- Expand tests

docs/vision-eval-20250902.md

@@ -0,0 +1,167 @@
+# Vision Evaluation - September 2, 2025
+
+## Executive Summary
+
+The current Form Submission MVP demonstrates solid progress toward the vision goals, with core infrastructure in place and key user flows implemented. The app successfully implements EFSP integration, session-based data management, and a working filing flow for Illinois Adult Name Change cases. However, several vision components remain incomplete or need refinement.
+
+**Overall Assessment: 70% Complete**
+
+## Vision Goal Analysis
+
+### ✅ **Achieved Goals**
+
+#### EFSP REST API Integration
+- **Status**: ✅ Complete
+- **Implementation**: Full integration with Suffolk's EFSP API for authentication, options discovery, and filing submission
+- **Evidence**: Comprehensive API views in `efile/api/` directory, auth handling, dropdown population from live API data
+
+#### Session Data Management
+- **Status**: ✅ Complete
+- **Implementation**: Robust session-based data storage with structured case data, party information, and file uploads
+- **Evidence**: Session API endpoints, data persistence across flow steps, temporary file storage
+
+#### Basic Auth/Session
+- **Status**: ✅ Complete
+- **Implementation**: Django-based authentication with user registration, login/logout, and session management
+- **Evidence**: User registration forms, login views, session-based auth tokens
+
+#### Local Deploy via Docker/Compose
+- **Status**: ✅ Complete
+- **Implementation**: Full Docker setup with compose configuration
+- **Evidence**: `Dockerfile`, `compose.yml`, and environment-specific settings
+
+#### CI with Ruff/Ty/Pytest
+- **Status**: ✅ Complete
+- **Implementation**: GitHub Actions workflow with type checking, linting, and testing
+- **Evidence**: `.github/workflows/ci.yml`, pyproject.toml configuration
+
+#### Illinois Adult Name Change Support
+- **Status**: ✅ Complete
+- **Implementation**: Dedicated case type configuration and form handling for Cook County Adult Name Change
+- **Evidence**: Case type config in `case_type_config.yml`, specialized form validation
+
+### 🔄 **Partially Implemented**
+
+#### Form Blocks Architecture
+- **Status**: 🔄 Partial (40%)
+- **Current State**: Basic form components exist but not as reusable, configurable blocks
+- **Gap**: Forms are hardcoded rather than built from composable Form Block components
+- **Next Steps**: Refactor forms to use configurable Form Block system
+
+#### Filing Flow Runner
+- **Status**: 🔄 Partial (60%)
+- **Current State**: Linear flow exists (login → options → expert form → upload → review → submit)
+- **Gap**: No configuration-driven flow system; flows are hardcoded in views
+- **Next Steps**: Implement YAML-based Filing Flow configuration system
+
+#### Review & Submit Step
+- **Status**: 🔄 Partial (70%)
+- **Current State**: Review page exists with case data summary
+- **Gap**: Summary could be more human-readable; needs better formatting
+- **Next Steps**: Enhance review page with clearer data presentation
+
+#### Mapping Layer
+- **Status**: 🔄 Partial (50%)
+- **Current State**: Basic field mapping exists in forms and API calls
+- **Gap**: No centralized, configurable mapping system
+- **Next Steps**: Create declarative mapping configuration system
+
+### ❌ **Missing Components**
+
+#### Configuration-Driven Form Blocks
+- **Status**: ❌ Not Implemented
+- **Vision**: Small set of validated input blocks (text, select, date, address) with basic theming
+- **Current State**: Hardcoded Django forms
+- **Impact**: Non-technical users cannot configure workflows without code changes
+
+#### Self-Service Filing Flow Configuration
+- **Status**: ❌ Not Implemented  
+- **Vision**: Non-technical users can create/edit Filing Flows without code
+- **Current State**: All flows are hardcoded in Python/templates
+- **Impact**: Major blocker for vision goal of self-service configuration
+
+#### Multiple Case Type Support
+- **Status**: ❌ Limited
+- **Vision**: Proof of feasibility for at least 2 other case types beyond Adult Name Change
+- **Current State**: Only Adult Name Change fully implemented
+- **Impact**: Cannot demonstrate system flexibility
+
+#### Guided Interview Experience
+- **Status**: ❌ Not Implemented
+- **Vision**: Plain-language labels, helper text, step-by-step guidance
+- **Current State**: Expert form is technical and overwhelming
+- **Impact**: Poor user experience for self-represented litigants
+
+## User Experience Assessment
+
+### Current User Journey
+1. **Registration/Login**: ✅ Working, clean interface
+2. **Options Selection**: ✅ Functional but technical (expert mode only)
+3. **Case Details**: ✅ Working but complex form
+4. **Document Upload**: ✅ Functional with S3 integration
+5. **Review**: ✅ Basic summary provided
+6. **Submission**: ✅ EFSP integration working
+
+### UX Gaps vs Vision
+- **Clarity**: Current interface is expert-focused, not beginner-friendly
+- **Guidance**: Lacks step-by-step guidance and plain-language instructions
+- **Progressive Disclosure**: Shows all options at once rather than guided flow
+- **Error Handling**: Basic validation exists but could be more user-friendly
+
+## Technical Architecture Assessment
+
+### Strengths
+- **Solid Foundation**: Django app with proper structure and separation of concerns
+- **API Integration**: Robust EFSP API integration with proper error handling
+- **Session Management**: Effective session-based data persistence
+- **Configuration Start**: Beginning of configuration system with YAML files
+- **Testing Infrastructure**: CI/CD pipeline with proper tooling
+
+### Areas for Improvement
+- **Form Block Architecture**: Need composable, reusable form components
+- **Configuration System**: Expand YAML-based configuration for full Filing Flows
+- **Error Handling**: Enhance user-facing error messages and recovery flows
+- **UI Components**: Move toward more modular, themeable UI components
+
+## Success Metrics Progress
+
+### Time-to-Submit (Target: 15 minutes)
+- **Current**: Estimated 20-25 minutes for technical users
+- **Gap**: Expert form complexity adds time; needs guided flow
+
+### First-Pass Acceptance (Target: ≥80%)
+- **Current**: Unknown (needs testing)
+- **Blocker**: Limited real-world testing data
+
+### Self-Service Configuration (Target: Non-technical user can edit flows)
+- **Current**: 0% - All configuration requires code changes
+- **Critical Gap**: No visual or YAML-based flow configuration
+
+### Fast Onboarding (Target: Quick Docker setup)
+- **Current**: ✅ Achieved - Docker compose setup works well
+
+## Priority Recommendations
+
+### High Priority (Core Vision Blockers)
+1. **Implement Form Block Architecture**: Create reusable, configurable form components
+2. **Build Filing Flow Configuration System**: YAML-based flow definitions
+3. **Create Guided Interview Mode**: User-friendly alternative to expert form
+4. **Add 2 More Case Types**: Demonstrate system flexibility
+
+### Medium Priority (UX Improvements)
+1. **Enhance Error Handling**: Better user-facing error messages
+2. **Improve Review Page**: More readable data summary
+3. **Add Helper Text System**: Step-by-step guidance and instructions
+
+### Low Priority (Polish)
+1. **UI Theming**: Consistent, professional styling
+2. **Performance Optimization**: Caching and response time improvements
+3. **Advanced Validation**: Cross-field and business rule validation
+
+## Conclusion
+
+The current MVP has established a solid technical foundation with working EFSP integration and basic filing capabilities. The core infrastructure supports the vision's goals, but the user experience and configuration flexibility need significant development to achieve the vision of self-service, guided filing flows.
+
+The most critical gap is the lack of configurable Form Blocks and Filing Flows, which prevents non-technical users from creating or modifying workflows. Addressing this gap should be the top priority for the next development phase.
+
+**Recommended Next Phase Focus**: Transform the current expert-mode system into a configurable, guided interview system that non-technical users can customize and self-represented litigants can easily navigate.