Feature/workflow management research #14

mryhmln · 2026-01-21T15:01:09Z

Design review requested

- Reorganize Safety Net Benefits API into 8 domains: Client Management, Intake, Eligibility, Case Management, Workflow, Communication, Scheduling, Document Management - Add detailed entity definitions for each domain - Add verification entities: VerificationRequirement (Eligibility), VerificationSource and VerificationTask (Workflow) - Document terminology decisions: Client, LivingArrangement, EligibilityUnit, Determination - Add decision log with alternatives, rationale, and "reconsider if" clauses - Add future considerations (Benefits, Appeals, Change Reporting, etc.) - Include proposed file structure and migration considerations

- Rename workflow-management-design.md to domain-design.md - Create docs/architecture/ for comprehensive design documents - Add 'Proposed Architecture' status note to clarify this is future state - Add link to domain design in README intro and documentation sections

- Update overview to show 7 domains + 2 cross-cutting concerns - Update data flow diagram to show Communication alongside Reporting - Show two paths: caseworker review (SNAP/TANF) and automated (MAGI Medicaid) - Fix Decision Log: Application lives in Intake, not Eligibility - Remove duplicate 'Explicit Tasks vs Workflow Engine' section - Update file structure to show cross-cutting/ folder for Communication - Update Implementation Phase 1 to clarify Communication is cross-cutting

Gap analysis against workflow-capabilities.txt: - Add Queue entity for task organization by team/county/program - Add AssignmentRule entity for automatic task routing - Add Office entity for geographic/organizational routing - Update Task with queueId, officeId, requiredSkills, returned_to_queue status - Update TaskAuditEvent with returned_to_queue and queue_changed events - Add batch operations note for bulk task management Split architecture documentation: - Move detailed Workflow schemas to domains/workflow.md - Move detailed Case Management schemas to domains/case-management.md - Move detailed Communication schemas to cross-cutting/communication.md - Update domain-design.md with links to domain files - Renumber sections after removing detailed schemas

- Rename AssignmentRule to WorkflowRule with ruleType field (assignment/priority) - Add priority-specific conditions (hasChildrenUnderAge, incomePercentFPL, isHomeless, daysUntilDeadline) - Add targetPriority action for priority rules - Add usage examples table - Update references in domain-design.md

- CaseWorkerSkill is now the primary entity with skillType (certification, language, specialization) - Certifications are one type of skill with issuedDate, expirationDate, issuingAuthority - Languages are another type with proficiencyLevel - Removes separate languagesSpoken field (now part of skills) - Update workflow.md skill matching to reference skills instead of certifications

- Add Capabilities table to workflow.md - Clarify distinction: Workflow tracks task state, Case Management tracks assignment history - Clarify distinction: WorkflowRule (rules) vs Office/Caseload/Skills (data)

…itecture - Add Configuration Management and Observability as cross-cutting concerns - Section 5: API Layer Organization - System APIs vs Process APIs distinction - Folder structure (domains/ for System APIs, processes/ for contracts) - Process API organization by capability with actor metadata - What this repo provides (specs, mocks, reference impl) - Mock server scope (System APIs only) - Section 6: Vendor Independence - Adapter pattern for vendor abstraction - Guidance for states to avoid lock-in - Section 7: Operational Architecture - Configuration Management for business users - Observability standards for operations staff - Renumber subsequent sections (8-12)

- System APIs vs Process APIs (two-layer architecture) - Mock server scope (System APIs only) - Process API organization (by capability, not actor) - Reference implementation purpose (educational, not extendable) - Vendor independence approach (adapter pattern) - Configuration vs code boundary (policy analyst vs developer)

Document decision to defer Experience Layer (Backend for Frontend), with explanation of what it is and GraphQL as the recommended future direction when client needs diverge.

- Update Section 1 intro to reference all 4 cross-cutting concerns - Update data flow diagram to show all 4 cross-cutting concerns - Add Configuration Management and Observability to Section 4 table with links to Section 7 where they're defined - Clarify that Reporting doesn't have its own schemas

api-patterns.yaml: - Error handling: response structure, error codes, HTTP status guidance - API versioning: URL-path strategy, compatibility rules, deprecation - Idempotency: Idempotency-Key header pattern for safe retries - Batch operations: POST /{resources}/batch pattern - All marked "STATUS: Not yet implemented" domain-design.md: - Section 12: Documentation Gaps - Links to api-patterns.yaml with implementation notes - Data retention & archival guidance - Event-driven architecture / webhooks patterns - Integration patterns (gateway, adapter, anti-corruption layer) - Notes on future docs needed (testing, security) - Section 13: References (renumbered, expanded) - Links to guides and ADRs - Related documentation table

Each section now indicates which API type it applies to: - [SYSTEM] - System APIs only (CRUD, list, search) - [PROCESS] - Process APIs only - [BOTH] - Both API types (naming, error handling, versioning) - [SYSTEM, PROCESS*] - Required for System, varies for Process Key distinctions: - List/search/CRUD patterns: System APIs only - Idempotency: Required for all Process API POSTs, System API creates only - Batch operations: Primarily System APIs - Shared components: Error responses shared, query params System only

New sections (all marked STATUS: Not yet implemented): - Authentication: OAuth 2.0/OIDC, API keys, mTLS - State-configurable IdP (Okta, Azure AD, state-specific) - Token validation requirements - Environment variable configuration guidance - Authorization: Scopes, RBAC, ABAC, field-level filtering - Standard scopes (applications:read, tasks:write, etc.) - Role hierarchy (client → caseworker → supervisor → admin) - Attribute-based rules (assigned cases only, same office, etc.) - Field-level masking (SSN visibility by role) - Rate Limiting: Standard headers, configurable tiers - Security Headers: HSTS, CORS, cache control - Audit Logging: Required fields, sensitive access, PII handling Updated domain-design.md: - Added new patterns to documentation gaps table - Note about state configurability for auth - Changed "Security & RBAC" future doc to "State Security Implementation Guide"

Split domain-design.md into focused documents: - domain-design.md: Sections 1-4 (domains, data flow, concerns, schemas) - api-architecture.md: Sections 5-7 (API layers, vendor independence, ops) - design-decisions.md: Section 8 (decision log with rationale) - roadmap.md: Sections 9-12 (migration, phases, future, gaps) - README.md: Index linking all architecture docs New API patterns in api-patterns.yaml: - Process API Metadata: x-actors, x-capability extensions - Correlation IDs: X-Correlation-ID header for request tracing - ETags / Optimistic Concurrency: If-Match, If-None-Match - Sorting: Standard sort query parameter - Long-Running Operations: Async pattern with status polling Roadmap lists additional API patterns to consider (not commitments): - Webhooks, partial responses, caching, hypermedia, etc.

- Link to architecture README instead of just domain-design.md - Architecture section now covers all 4 architecture documents

Workflow domain (task-management capability): - POST /processes/tasks/claim - Caseworker claims task - POST /processes/tasks/complete - Complete task with outcome - POST /processes/tasks/release - Return task to queue - POST /processes/tasks/reassign - Supervisor reassigns task - POST /processes/tasks/escalate - Escalate to supervisor - POST /processes/tasks/bulk-reassign - Bulk reassignment - POST /processes/tasks/route - Apply workflow rules - POST /processes/verification/start - Start data verification - POST /processes/verification/complete - Record verification result Case Management domain (case-management capability): - POST /processes/assignments/assign - Assign worker to case/task - POST /processes/cases/transfer - Transfer case to office/worker - POST /processes/teams/rebalance - Redistribute team workload - POST /processes/workers/update-availability - Update worker status - GET /processes/workers/capacity - Get worker capacity info

…e}/{action} Updated path pattern from /processes/{resource}/{action} to include domain: - /processes/workflow/tasks/claim (was /processes/tasks/claim) - /processes/case-management/workers/assign (was /processes/assignments/assign) - /processes/communication/notices/send (example for cross-cutting) Convention: When an operation involves multiple resources, place it under the resource being acted upon (not the primary output). Updated files: - api-architecture.md: folder structure, examples, convention documentation - api-patterns.yaml: path_convention section, updated all examples - workflow.md: all Process API paths - case-management.md: all Process API paths

Design decisions: - Added Process API path convention decision with /processes/{domain}/{resource}/{action} pattern and 'resource being acted upon' convention Communication domain: - Added Capabilities section (caseworker, supervisor, system, client) - Added Process APIs section with send, approve, retry operations x-capability alignment: - Renamed application-intake → intake (match domain) - Renamed task-management → workflow (match domain) - Removed verification as separate capability (part of workflow) - Added client-management capability - Added note that x-capability should match domain in path - Updated workflow.md to use x-capability: workflow (was task-management/verification)

- communication.md: Replace entity fields with Process API endpoints - case-management.md: Replace entity fields with Process API endpoints - workflow.md: Replace entity fields with Process API endpoints

- workflow.md: Add missing capabilities (create task, monitor team workload, reports) - workflow.md: Add POST /processes/workflow/tasks/create Process API - workflow.md: Rename "Route task by rules" to include prioritization - case-management.md: Simplify capabilities section, reference workflow.md

- workflow.md: Add "Tasks vs Cases" section with comparison table - workflow.md: Add caseId field to Task schema (application-level vs case-level tasks) - workflow.md: Add case capabilities (assign worker, transfer case) to capabilities table - workflow.md: Reorganize Supervisor capabilities into Tasks/Cases/Monitoring groups - case-management.md: Add "Cases vs Tasks" section with cross-reference

- Task: Replace hardcoded taskType enum with taskTypeCode reference - Task: Add slaTypeCode reference to SLAType configuration - WorkflowRule: Replace fixed condition fields with JSON Logic expressions - Add TaskType and SLAType configuration schemas (code as PK) - Add TODO markers for standardizing ProgramType enum across schemas - Document JSON Logic and configuration entity decisions in design-decisions.md

- Add Quality Attributes Summary section to api-architecture.md as central index - Add Performance section (caching TTLs, pagination limits, query complexity) - Add Security section (data classification, PII handling) - Add Compliance section (retention, deletion, regulatory references) - Add API-level SLI metrics to Observability section - Add Operational Metrics section to workflow.md with domain-specific SLIs - Add Circuit Breakers pattern to api-patterns.yaml - Add Data Classification pattern with x-data-classification extension - Update roadmap.md with compliance cross-references

- Update EligibilityRequest to support requestType field (initial, recertification, renewal, change_report) instead of separate Recertification entity - Add status table clarifying design vs implementation status per domain - Workflow design is ready for review; other domains are work in progress - Remove redundant summary tables from design-decisions.md

lkacenja · 2026-01-21T22:34:03Z