Plan: Documentation Completeness

On this page

Status

Step Description Status

1

Create role-based user guides (caseworker, eligibility specialist, supervisor, applicant)

In progress — docs/modules/ROOT/pages/guide/caseworker.adoc exists; other roles not yet written

2

Create per-service API reference pages with endpoint tables, schemas, and examples

Done (2026-04-12) — 13 pages under docs/modules/ROOT/pages/api/ (delivered via documentation-pass plan)

3

Create deployment guide with environment variables, database setup, and security hardening

Done (2026-04-12) — docs/modules/ROOT/pages/deployment-guide.adoc (233 lines)

4

Create security operations runbook with severity classification, remediation SLAs, incident response

Done (2026-04-12) — docs/modules/ROOT/pages/security-operations.adoc

5

Create NIST SP 800-53 Rev. 5 control mapping

Done (2026-04-12) — docs/modules/ROOT/pages/nist-architecture-mapping.adoc (237 lines)

6

Create ATO readiness checklist

Done (2026-04-12) — docs/modules/ROOT/pages/ato-readiness.adoc

7

Create per-service data model documentation with column descriptions and ERDs

Not started

8

Create state machine documentation with Mermaid diagrams for all stateful entities

Done (2026-04-12) — docs/modules/ROOT/pages/state-machines.adoc

9

Create design documents with UI mockups for worker portal modules

Not started

10

Create UI module-to-role mapping page

Done (2026-04-28) — docs/modules/ROOT/pages/portal-modules.adoc extracts the 9-module × 5-role matrix that previously lived only inside this plan, plus a planned applicant-portal section keyed to ADR-008. Cross-linked from auditor-handbook.adoc and rbac-matrix.adoc. Antora nav.adoc updated.

11

Create configuration reference enumerating all environment variables per service

Done (2026-04-12) — docs/modules/ROOT/pages/configuration-reference.adoc

12

Create troubleshooting guide for common devstack, testing, and development issues

Done (2026-04-12) — docs/modules/ROOT/pages/troubleshooting.adoc

13

Create consolidated federal requirements mapping document

Done (2026-04-12) — docs/modules/ROOT/pages/federal-requirements.adoc

14

Create screenshots page organized by portal module

Not started

15

Create CLI reference page (scaffolded for canopy-cli plan)

Done — docs/modules/ROOT/pages/cli.adoc exists (262 lines) covering all cargo xtask subcommands. Drift cleanup (the page shipped via the documentation-pass plan but Status row was never flipped).

16

Create known issues and lessons learned document

Done (2026-04-28) — docs/modules/ROOT/pages/known-issues.adoc (8 categories: Devstack, Keycloak, Testing, JDM Rulesets, Event Bus, Database, Cross-program orchestration, plus a "When to add an entry" guide). Format is symptom / root cause / resolution per row. Cross-refs the internal Known Issues page for contributor-only entries (cargo deny, Rust 2024 reserved keywords). nav.adoc adds the page under Developer Guide.

17

Create user testing guide for UAT facilitators

Done (2026-04-29) — docs/modules/ROOT/pages/user-testing-guide.adoc covers test environment setup, seed data, role-based scenarios (caseworker / eligibility specialist / supervisor / QC reviewer / applicant), data collection (observation guide + notes template + S1/S2/S3 severity classification), accessibility testing (NVDA/VoiceOver/Orca screen-reader protocol + keyboard-only navigation + axe-core dark-theme spot-check), structured interview questions + 5-point satisfaction scale, weekly reporting format, cross-refs to RBAC matrix, portal modules, federal requirements. nav.adoc adds the page under Developer Guide.

18

Update Antora nav.adoc with all new pages

Done (2026-04-29) — Drift cleanup. Every page created by Steps 2-17 has been wired into docs/modules/ROOT/nav.adoc as it shipped (verified by a grep audit on 2026-04-29: all 26 .adoc files under docs/modules/ROOT/pages/ and pages/runbooks/ appear in nav). Future page additions add their nav entry in the same MR per project convention; nav drift is structurally low-risk.

Epic: &43
Branch: docs/documentation-completeness
Labels: type::documentation, priority::high, program::infrastructure

Context

A cross-project documentation audit compared Canopy’s Antora site against CRAIG’s and identified 17 structural documentation categories that CRAIG covers which Canopy has no equivalent for — not even a skeleton page.

Canopy’s existing documentation is strong in three areas: developer guides, architecture decisions, and implementation plans. But it is entirely absent in categories that a production government eligibility system requires:

  1. No user guides. Caseworkers, eligibility specialists, and supervisors arriving for September 2026 UAT will have no documentation explaining how to use the system. Training materials cannot be written without a reference document to train from.

  2. No operations documentation. An ops team deploying Canopy to production would have to grep source code for environment variables, guess at database setup procedures, and invent incident response processes from scratch. There is no deployment guide, no security operations runbook, no NIST control mapping, and no ATO readiness checklist.

  3. No data model or state machine documentation. The database schema is documented only in SQL migration files. There are no column descriptions, no ERDs, and no state machine diagrams. Anyone reviewing the system for compliance or integration purposes must read raw SQL.

  4. No API reference. Endpoint tables exist in the Service Catalog but there are no public-facing per-service API pages with request/response schemas, error codes, or examples. External integrators and CLI developers have nowhere to look.

  5. No visual documentation. No screenshots, no UI mockups, no design documents. For a system entering UAT, stakeholders and testers need visual reference material.

These are not features that grow naturally as code lands. They are documentation categories that must be planned, scaffolded, and populated deliberately. Many can be written in parallel with portal development (Month 6) since they document the system as it exists today.

This plan covers all 17 missing categories. CRAIG’s equivalent pages serve as structural templates — the content is Canopy-specific.

Scope

In scope:

  • 4 role-based user guides (caseworker/eligibility specialist, supervisor, admin, applicant)

  • 10+ per-service API reference pages

  • Deployment guide with per-service environment variables and security hardening

  • Security operations runbook with CVSS severity classification and remediation SLAs

  • NIST SP 800-53 Rev. 5 control mapping to Canopy implementation

  • ATO readiness checklist (infrastructure, security, compliance, data exchange, testing)

  • Per-service data model pages with table descriptions and Mermaid ERDs

  • State machine diagrams for all stateful entities (applications, determinations, appeals, enrollments, certifications, notices)

  • Design documents with SVG or ASCII mockups for worker portal modules

  • UI module-to-role mapping page

  • Complete configuration reference (all env vars per service)

  • Troubleshooting guide for devstack, testing, and development

  • Consolidated federal requirements mapping (7 CFR, 42 CFR, IRC §6103, 42 USC)

  • Screenshots page (populated as portal routes land)

  • CLI reference page (scaffolded for future canopy-cli)

  • Known issues and lessons learned page

  • User testing guide for UAT facilitators

  • Antora nav.adoc updates for all new pages

Out of scope:

  • Multi-language translations of documentation (post-UAT)

  • Video tutorials (separate initiative)

  • Printed training manuals (UAT will use digital docs)

  • Portal route implementation (separate plan: worker-portal-snap)

Design

Page Organization

New pages integrate into the existing Antora nav structure. Following CRAIG’s proven organization:

docs/modules/ROOT/pages/
  # Getting Started (existing)
  index.adoc
  why-canopy.adoc
  roadmap.adoc
  glossary.adoc
  devstack.adoc                    (new — extract from local-dev.md)
  screenshots.adoc                 (new)
  user-testing-guide.adoc          (new)

  # User Guide (new section)
  guide/
    caseworker.adoc                (new)
    supervisor.adoc                (new)
    admin.adoc                     (new)
    applicant.adoc                 (new)

  # API Reference (new section)
  api/
    index.adoc                     (new)
    canopy-rules.adoc              (new)
    canopy-persons.adoc            (new)
    canopy-applications.adoc       (new)
    canopy-eligibility.adoc        (new)
    canopy-snap.adoc               (new)
    canopy-verification.adoc       (new)
    canopy-enrollment.adoc         (new)
    canopy-renewals.adoc           (new)
    canopy-notices.adoc            (new)
    canopy-appeals.adoc            (new)
    canopy-security.adoc           (new)
    canopy-web.adoc                (new)

  # Architecture (existing, additions)
  data-model-persons.adoc          (new)
  data-model-applications.adoc     (new)
  data-model-snap.adoc             (new)
  data-model-appeals.adoc          (new)
  data-model-enrollment.adoc       (new)
  data-model-renewals.adoc         (new)
  data-model-notices.adoc          (new)
  data-model-security.adoc         (new)
  state-machines.adoc              (new)
  federal-requirements.adoc        (new)

  # Design Documents (new section)
  design/
    ui-overview.adoc               (new — module-to-role map)
    dashboard.adoc                 (new — worker dashboard mockup)
    case-search.adoc               (new — case search and results)
    case-detail.adoc               (new — tabbed case detail view)
    application-intake.adoc        (new — application processing)
    determination-review.adoc      (new — eligibility determination)
    renewal-queue.adoc             (new — renewal management)
    notices.adoc                   (new — notice generation and delivery)
    appeals.adoc                   (new — appeals and fair hearings)

  # Developer Guide (existing, additions)
  developer-guide.adoc
  implementation-guide.adoc
  jurisdiction-onboarding.adoc
  configuration-reference.adoc     (new)
  troubleshooting.adoc             (new)
  cli.adoc                         (new — scaffolded)

  # Operations (new section)
  deployment-guide.adoc            (new)
  security-operations.adoc         (new)
  nist-architecture-mapping.adoc   (new)
  ato-readiness.adoc               (new)

Content Approach

Each page follows a consistent structure:

  • User guides: Task-oriented (login → dashboard → workflow → complete). Role-based: each guide covers only what that role can see and do. Include navigation breadcrumbs and cross-references to related guides.

  • API reference: Auto-generated tables from utoipa annotations where possible. Manual endpoint documentation following the pattern: method, path, description, request body, response body, error codes, example. Link to Swagger UI for interactive testing.

  • Data models: One page per service database. Table listing with column name, type, nullable, description. Mermaid ERD showing relationships. Index strategy notes.

  • State machines: Mermaid stateDiagram-v2 for each stateful entity. Valid transitions listed with triggering actions and required conditions.

  • Design documents: SVG mockups (hand-drawn style) embedded in AsciiDoc. Each page covers one UI module with: purpose, user roles, screen layout, interactions, accessibility notes.

  • Operations: Written for an ops team that has never seen the codebase. Environment variable tables with name, description, default, required/optional. Step-by-step procedures for common operations (deploy, backup, rotate secrets, respond to incident).

Steps

Step 1: Role-based user guides

Files: docs/modules/ROOT/pages/guide/caseworker.adoc, guide/supervisor.adoc, guide/admin.adoc, guide/applicant.adoc

Write four user guides following CRAIG’s structure:

  1. Caseworker / Eligibility Specialist Guide: Logging in, dashboard overview, searching for cases, viewing case details (household, income, determination, notices, appeals, activity tabs), processing applications (expedited screening, identity verification), reviewing eligibility determinations, managing renewals, generating notices

  2. Supervisor Guide: Caseload oversight, timeliness monitoring (processing deadlines, appeal clocks), approval workflows, quality control reviews, federal reporting overview, managing worker assignments

  3. Administrator Guide: User management in Keycloak, jurisdiction configuration, federal parameter updates (annual FPL, allotment tables), NIST security controls, audit log review, breach alert management, system monitoring

  4. Applicant Guide: How to apply for benefits (when portal exists), required documentation per program, checking application status, understanding notices, filing appeals, reporting changes, renewal process

Note: caseworker and applicant guides will be skeletal until portal routes land. Write the structure and navigation now; populate with screenshots and step-by-step details as UI is built.

Step 2: Per-service API reference

Files: docs/modules/ROOT/pages/api/index.adoc and 12 service-specific pages

  1. Create api/index.adoc with overview, authentication requirements, common headers, error format (RFC 9457), pagination, and links to per-service pages

  2. For each implemented service, create a page with:

    • Service description and base URL

    • Authentication requirements (role minimums)

    • Endpoint table: method, path, description, minimum role

    • Request/response examples for key endpoints (JSON)

    • Error codes with descriptions

    • Link to Swagger UI (/swagger-ui)

  3. Services to document: canopy-rules, canopy-persons, canopy-applications, canopy-eligibility, canopy-snap, canopy-verification, canopy-enrollment, canopy-renewals, canopy-notices, canopy-appeals, canopy-security, canopy-web

  4. Add cargo xtask api-docs command to auto-generate endpoint tables from utoipa annotations

Step 3: Deployment guide

Files: docs/modules/ROOT/pages/deployment-guide.adoc

Write a comprehensive deployment guide covering:

  1. Architecture overview (19 service containers + 5 program databases + infrastructure)

  2. Infrastructure prerequisites (PostgreSQL, RabbitMQ, Keycloak, S3-compatible storage)

  3. Per-service environment variable table (name, description, default, required)

  4. Database setup: creating databases, running migrations, configuring per-program isolation (ADR-001)

  5. Keycloak configuration: realm import, client creation, role mapping, JWKS endpoint

  6. RabbitMQ configuration: exchange creation, queue binding, user permissions

  7. S3 configuration: bucket creation, access policies

  8. Container deployment: Docker Compose profiles (ADR-005), health check verification

  9. Security hardening: TLS for all connections, secret injection, log redaction, network segmentation

  10. Horizontal scaling: stateless services, session affinity for BFF, database connection pool sizing

  11. Monitoring: Prometheus metrics endpoint, health check endpoints, log aggregation

Step 4: Security operations runbook

Files: docs/modules/ROOT/pages/security-operations.adoc

Write a security operations runbook covering:

  1. Vulnerability severity classification (CVSS v3.1 base score + contextual adjustments)

  2. PII multiplier: vulnerabilities affecting FTI, SSN, or income data increase one severity level

  3. Remediation SLAs: critical (24h patch / 48h deploy), high (7d / 14d), medium (30d / 60d), low (90d / next release)

  4. Escalation procedures: who to notify, when to invoke incident response

  5. Penetration testing process: scope, frequency, reporting, remediation tracking

  6. Incident response procedures: detection, containment, eradication, recovery, lessons learned

  7. Key rotation procedures: Keycloak signing keys, JWS determination keys, field encryption keys

  8. Secret rotation: database credentials, RabbitMQ credentials, S3 access keys

  9. Audit log review: frequency, what to look for, escalation triggers

  10. Breach notification: timeline requirements per program (IRS Pub 1075: 24h for FTI, HIPAA: 60 days)

Step 5: NIST control mapping

Files: docs/modules/ROOT/pages/nist-architecture-mapping.adoc

Map NIST SP 800-53 Rev. 5 controls to Canopy implementation:

  1. AC (Access Control): AC-2 (account management → Keycloak), AC-3 (access enforcement → require_role middleware), AC-6 (least privilege → role hierarchy), AC-7 (unsuccessful logon → Keycloak brute force detection), AC-12 (session termination → tower-sessions TTL)

  2. AU (Audit): AU-2 (event logging → canopy-security wildcard subscriber), AU-3 (audit content → EventEnvelope fields), AU-6 (audit review → security dashboard), AU-9 (audit protection → separate database)

  3. CM (Configuration Management): CM-2 (baseline configuration → Docker images), CM-6 (configuration settings → env vars), CM-7 (least functionality → minimal Alpine images)

  4. IA (Identification & Authentication): IA-2 (user identification → Keycloak OIDC), IA-5 (authenticator management → JWKS rotation), IA-8 (non-org users → applicant portal)

  5. SC (Systems & Communications): SC-8 (transmission confidentiality → rustls TLS), SC-12 (cryptographic key management → canopy-signing key rotation), SC-13 (cryptographic protection → ECDSA P-256)

  6. SI (System & Information Integrity): SI-2 (flaw remediation → cargo-audit, dependency scanning), SI-4 (system monitoring → canopy-security breach alerts), SI-10 (information input validation → validator crate)

Each control entry includes: control ID, control title, Canopy implementation, relevant code/config paths, and assessment status.

Step 6: ATO readiness checklist

Files: docs/modules/ROOT/pages/ato-readiness.adoc

Create a comprehensive pre-ATO checklist organized by category:

  1. Infrastructure: TLS on all connections, DNS configuration, Keycloak realm, per-program databases, RabbitMQ exchange, S3 buckets, container orchestration, network segmentation, logging infrastructure

  2. Security Configuration: Session security (PostgreSQL-backed, secure flags), CORS (explicit origins), rate limiting, security headers, RBAC enforcement, CSRF tokens, JWS signing keys deployed

  3. Compliance Documentation: NIST SP 800-53 assessment complete, Privacy Impact Assessment, data retention policy, vulnerability disclosure policy, remediation SLAs documented, IRS Pub 1075 safeguard procedures (if FTI), HIPAA compliance documentation (if Medicaid)

  4. Data Exchange: IEVS adapter configured, SAVE adapter configured, EBT vendor integration, partner data sharing agreements in place, FTI audit logging active

  5. Testing: Penetration test complete, E2E test suite passing, integration tests passing, load test baseline established, disaster recovery tested, accessibility audit complete (WCAG 2.1 AA)

Step 7: Data model documentation

Files: docs/modules/ROOT/pages/data-model-persons.adoc, data-model-applications.adoc, data-model-snap.adoc, data-model-appeals.adoc, data-model-enrollment.adoc, data-model-renewals.adoc, data-model-notices.adoc, data-model-security.adoc

For each service database, create a page containing:

  1. Service name and database name (e.g., canopy-persons → postgres default, canopy-snap → postgres-snap)

  2. Table listing with columns: name, type, nullable, default, description

  3. Mermaid ERD (erDiagram) showing foreign key relationships

  4. Index listing with columns covered and purpose

  5. Constraints (unique, check, foreign key) with names and descriptions

  6. Notes on data isolation per ADR-001 and ADR-004

Source data from migration files in each service’s migrations/ directory.

Step 8: State machine documentation

Files: docs/modules/ROOT/pages/state-machines.adoc

Document all stateful entities with Mermaid stateDiagram-v2 diagrams:

  1. Application status: draft → submitted → screening → pending_verification → determined → withdrawn

  2. Determination status: pending → approved → denied → terminated → sanctioned → time_limit_exceeded

  3. Appeal status: filed → scheduled → hearing_held → decision_issued → implemented

  4. Enrollment status: pending → active → suspended → terminated → expunged

  5. Certification period status: active → interim_contact_due → renewal_due → expired → renewed

  6. Notice status: generated → stored → delivered → failed

  7. IPV case status: referred → adh_notice_sent → hearing_scheduled → decision_issued → penalty_active → penalty_completed

  8. Verification status: pending → matched → discrepancy → resolved

Each diagram includes: valid transitions, triggering actions, guard conditions, and terminal states.

Step 9: Design documents with UI mockups

Files: docs/modules/ROOT/pages/design/ui-overview.adoc, design/dashboard.adoc, design/case-search.adoc, design/case-detail.adoc, design/application-intake.adoc, design/determination-review.adoc, design/renewal-queue.adoc, design/notices.adoc, design/appeals.adoc

Create design documents for each worker portal module:

  1. UI Overview (ui-overview.adoc): User roles (caseworker, eligibility_specialist, supervisor, quality_control, admin), module-to-role access map, navigation structure, Orchard design system reference

  2. Dashboard: Caseload summary, pending actions queue, expiring certifications, overdue renewals, recent activity feed

  3. Case Search: Search by name/SSN/case number, filter by status/program/worker, sortable results table, pagination

  4. Case Detail: Tabbed view (Household, Income/Assets, Determination, Notices, Appeals, Activity), read-only vs. editable sections per role

  5. Application Intake: Application form flow, expedited screening indicator, program selection, household composition

  6. Determination Review: Eligibility summary, deduction breakdown, benefit calculation, approve/deny actions with reason codes

  7. Renewal Queue: Certification periods nearing expiration, interim contact tracking, simplified reporting forms

  8. Notices: Notice generation trigger, template selection, preview, delivery status tracking

  9. Appeals: Appeal filing form, continued benefits indicator, hearing scheduling, decision recording

Each page includes: purpose, roles with access, screen layout (SVG or ASCII mockup), interaction notes, accessibility requirements.

Step 10: UI module-to-role mapping

Files: docs/modules/ROOT/pages/design/ui-overview.adoc (created in Step 9)

Create a matrix showing which portal modules each role can access:

Module Caseworker Eligibility Specialist Supervisor Quality Control Admin

Dashboard

View

View

View + Team

View

View + System

Case Search

Search + View

Search + View

Search + View

Search + View

Search + View

Application Intake

Create + Edit

Create + Edit

Create + Edit + Approve

View

View

Determination

View

Determine + Sign

Review + Override

Review

View

Notices

Generate

Generate

Generate + Approve

View

View

Appeals

File + View

View

Schedule + Decide

View

View

Renewals

Process

Process

Assign + Monitor

Review

View

Audit Logs

—

—

View Own Team

View All

View All + Export

User Management

—

—

—

—

Full Access

Step 11: Configuration reference

Files: docs/modules/ROOT/pages/configuration-reference.adoc

Enumerate all environment variables for every service. Structure: one table per service, columns: variable name, description, default, required.

  1. Shared settings (all services): CANOPY_<SVC>__PORT, DATABASE_URL, RABBITMQ_URL, KEYCLOAK_ISSUER, KEYCLOAK_URL, JURISDICTION, LOG_LEVEL, CORS_ORIGINS, RATE_LIMIT_RPM, OTEL_EXPORTER_OTLP_ENDPOINT

  2. canopy-web specific: SESSION_TTL_SECONDS, THEME_DIR, BRANDING_*

  3. canopy-portal specific: SESSION_TTL_SECONDS, DEFAULT_LOCALE, LOCALES_DIR

  4. canopy-snap specific: RULES_URL, RULESETS_DIR

  5. canopy-enrollment specific: EBT_ADAPTER (noop vs. production)

  6. canopy-verification specific: IEVS_ADAPTER, SAVE_ADAPTER

  7. canopy-notices specific: S3_BUCKET, S3_ENDPOINT, TYPST_TEMPLATES_DIR

  8. canopy-signing: CANOPY_SIGNING_KEY, CANOPY_VERIFY_KEY_*

Source: grep all ServiceSettings structs and std::env::var calls in the codebase.

Step 12: Troubleshooting guide

Files: docs/modules/ROOT/pages/troubleshooting.adoc

Document common issues and solutions:

  1. DevStack: Keycloak not starting (realm import failure), RabbitMQ connection refused (readiness timing), PostgreSQL port conflicts, Garage S3 initialization, service health check failures

  2. Testing: Integration tests silently skipping (devstack not running), 401 errors (token expiry), random timeouts (pool exhaustion), migration conflicts

  3. Development: CORS errors in browser, JWT validation failures (clock skew), Typst compilation errors, sqlx offline mode issues

  4. Docker: Multi-stage build failures, Alpine dependency issues, image size bloat

  5. Common error messages: map specific error strings to causes and solutions

Step 13: Federal requirements mapping

Files: docs/modules/ROOT/pages/federal-requirements.adoc

Consolidate all federal regulation references into a single mapping document:

  1. SNAP (7 CFR 271-283): Eligibility (§273.2), income (§273.9), deductions (§273.9(d)), allotment (§273.10), ABAWD (§273.24), verification (§273.2(f)), fair hearings (§273.15), IPV (§273.16), certification periods (§273.10(f)), EBT (§274)

  2. TANF (45 CFR 260-265): Time limits, work requirements, sanctions, FTI handling

  3. Medicaid (42 CFR 430-456): MAGI methodology, FDSH verification, continuous eligibility

  4. IRS Pub 1075: FTI safeguarding, audit logging, access restrictions, breach notification (24h)

  5. HIPAA: PHI protection, minimum necessary, breach notification (60 days)

  6. Section 508: WCAG 2.1 AA, keyboard navigation, screen reader compatibility

  7. Computer Matching Act: Data matching agreements, due process protections

Each entry includes: regulation citation, requirement summary, Canopy implementation status, relevant service/module.

Step 14: Screenshots page

Files: docs/modules/ROOT/pages/screenshots.adoc

Create a screenshots page organized by module:

  1. Structure the page with sections for: Login, Dashboard, Case Search, Case Detail, Application Processing, Determination, Notices, Appeals, Admin (Security, Audit Logs)

  2. Populate with placeholder text: "Screenshot will be added when [module] routes are implemented"

  3. As portal routes land (worker-portal-snap plan), capture screenshots and embed them

  4. Include both light and dark theme variants (Orchard design system supports both)

Step 15: CLI reference

Files: docs/modules/ROOT/pages/cli.adoc

Scaffold a CLI reference page for the future canopy-cli:

  1. Overview: purpose (CLI/API/UI parity per ADR-007), installation, authentication

  2. Configuration: profile-based setup (~/.config/canopy/profiles.toml), service URLs, token management

  3. Command groups (scaffolded from canopy-cli plan): canopy rules, canopy person, canopy application, canopy determine, canopy appeal, canopy notice, canopy enroll, canopy renew, canopy export

  4. Output formats: JSON (default), table, CSV

  5. Mark as "Planned — implementation tracked in canopy-cli plan"

Step 16: Known issues and lessons learned

Files: Known Issues

Document known gotchas and workarounds:

  1. askama_axum version constraint requires specific version pinning

  2. sqlx offline mode not used — requires running database for compilation

  3. NoopAdapters compiled into production binary (until feature-gated)

  4. Integration tests silently skip when devstack is down

  5. Pre-commit challenge adds friction without catching issues pre-push doesn’t

  6. CORS defaults to * — must be overridden for any non-dev deployment

  7. Test count discrepancy between docs (should use cargo nextest list as source of truth)

  8. Fluent i18n in canopy-portal is a stub with no loaded translations

  9. Session tests in canopy-web are TODO stubs

Add new entries as they’re discovered. Review and prune quarterly.

Step 17: User testing guide

Files: docs/modules/ROOT/pages/user-testing-guide.adoc

Write guidance for UAT facilitators:

  1. Test environment setup: Devstack configuration, seed data loading, test user accounts (roles and credentials)

  2. Test scenarios by role: Caseworker workflows (intake → determine → enroll), supervisor workflows (review → approve → report), applicant workflows (apply → check status → appeal)

  3. Data collection: What to observe (task completion time, error recovery, confusion points), how to record (screen recording, notes template, severity classification)

  4. Accessibility testing: Screen reader testing protocol, keyboard-only navigation checklist, color contrast verification

  5. Feedback collection: Structured interview questions, satisfaction rating scales, open-ended improvement suggestions

  6. Reporting: UAT report template, issue classification (blocker, major, minor, enhancement), remediation tracking

Step 18: Update Antora nav.adoc

Files: docs/modules/ROOT/nav.adoc

Add all new pages to the navigation structure:

* xref:index.adoc[Overview]
** xref:why-canopy.adoc[Why Canopy?]
** xref:roadmap.adoc[Roadmap]
** xref:screenshots.adoc[Screenshots]
** xref:user-testing-guide.adoc[User Testing Guide]

* User Guide
** xref:guide/caseworker.adoc[Caseworker & Eligibility Specialist Guide]
** xref:guide/supervisor.adoc[Supervisor Guide]
** xref:guide/admin.adoc[Administrator Guide]
** xref:guide/applicant.adoc[Applicant Guide]
** API Reference
*** xref:api/index.adoc[Overview]
*** xref:api/canopy-rules.adoc[Rules Engine]
*** xref:api/canopy-persons.adoc[Persons & Households]
*** xref:api/canopy-applications.adoc[Applications]
*** xref:api/canopy-eligibility.adoc[Eligibility Orchestrator]
*** xref:api/canopy-snap.adoc[SNAP Program]
*** xref:api/canopy-verification.adoc[Verification]
*** xref:api/canopy-enrollment.adoc[Enrollment & EBT]
*** xref:api/canopy-renewals.adoc[Renewals & Certification]
*** xref:api/canopy-notices.adoc[Notices]
*** xref:api/canopy-appeals.adoc[Appeals & Fair Hearings]
*** xref:api/canopy-security.adoc[Security & Audit]
*** xref:api/canopy-web.adoc[Worker Portal]

* Architecture & Design
** (existing ADRs)
** Data Models
*** xref:data-model-persons.adoc[Persons & Households]
*** xref:data-model-applications.adoc[Applications]
*** xref:data-model-snap.adoc[SNAP]
*** xref:data-model-appeals.adoc[Appeals]
*** xref:data-model-enrollment.adoc[Enrollment]
*** xref:data-model-renewals.adoc[Renewals]
*** xref:data-model-notices.adoc[Notices]
*** xref:data-model-security.adoc[Security & Audit]
** xref:state-machines.adoc[State Machines]
** xref:federal-requirements.adoc[Federal Requirements Mapping]
** Design Documents
*** xref:design/ui-overview.adoc[UI Module Map]
*** xref:design/dashboard.adoc[Dashboard]
*** xref:design/case-search.adoc[Case Search]
*** xref:design/case-detail.adoc[Case Detail]
*** xref:design/application-intake.adoc[Application Intake]
*** xref:design/determination-review.adoc[Determination Review]
*** xref:design/renewal-queue.adoc[Renewal Queue]
*** xref:design/notices.adoc[Notices]
*** xref:design/appeals.adoc[Appeals]

* Developer Guide
** (existing pages)
** xref:configuration-reference.adoc[Configuration Reference]
** xref:troubleshooting.adoc[Troubleshooting]
** xref:cli.adoc[CLI Reference]

* Operations
** xref:deployment-guide.adoc[Deployment Guide]
** xref:security-operations.adoc[Security Operations]
** xref:nist-architecture-mapping.adoc[NIST Architecture Mapping]
** xref:ato-readiness.adoc[ATO Readiness Checklist]

* Plans
** (existing plan structure)

Files Touched

File Change

docs/modules/ROOT/pages/guide/caseworker.adoc

New: caseworker and eligibility specialist user guide

docs/modules/ROOT/pages/guide/supervisor.adoc

New: supervisor user guide

docs/modules/ROOT/pages/guide/admin.adoc

New: administrator user guide

docs/modules/ROOT/pages/guide/applicant.adoc

New: applicant user guide

docs/modules/ROOT/pages/api/*.adoc

New: 13 API reference pages (index + 12 services)

docs/modules/ROOT/pages/deployment-guide.adoc

New: deployment and operations guide

docs/modules/ROOT/pages/security-operations.adoc

New: security operations runbook

docs/modules/ROOT/pages/nist-architecture-mapping.adoc

New: NIST SP 800-53 control mapping

docs/modules/ROOT/pages/ato-readiness.adoc

New: ATO readiness checklist

docs/modules/ROOT/pages/data-model-*.adoc

New: 8 data model pages with ERDs

docs/modules/ROOT/pages/state-machines.adoc

New: state machine diagrams for all stateful entities

docs/modules/ROOT/pages/design/*.adoc

New: 9 design documents with UI mockups

docs/modules/ROOT/pages/configuration-reference.adoc

New: complete environment variable reference

docs/modules/ROOT/pages/troubleshooting.adoc

New: common issues and solutions

docs/modules/ROOT/pages/federal-requirements.adoc

New: consolidated federal regulation mapping

docs/modules/ROOT/pages/screenshots.adoc

New: application screenshots (populated as portal lands)

docs/modules/ROOT/pages/cli.adoc

New: CLI reference (scaffolded)

docs/modules/ROOT/pages/user-testing-guide.adoc

New: UAT facilitator guide

Known Issues

New: known issues and lessons learned

docs/modules/ROOT/nav.adoc

Updated: all new pages added to navigation

Execution Priority

Priority Step Effort Reason

P0

Step 3 (Deployment guide)

Medium

Ops team needs this before any production deployment

P0

Step 11 (Configuration reference)

Medium

Ops team cannot deploy without knowing all env vars

P0

Step 7 (Data models)

Medium

Compliance reviewers and integrators need schema documentation

P1

Step 4 (Security operations)

Medium

Required for ATO; remediation SLAs must be defined before production

P1

Step 5 (NIST mapping)

Medium

Required for ATO process

P1

Step 6 (ATO readiness)

Small

Checklist format; depends on Steps 4 and 5

P1

Step 8 (State machines)

Small

Quick to write from existing code; high reference value

P1

Step 13 (Federal requirements)

Medium

Auditors need a single consolidated reference

P2

Step 1 (User guides)

Large

Blocked on portal routes; scaffold now, populate during UAT prep

P2

Step 2 (API reference)

Medium

Can be partially auto-generated from utoipa

P2

Step 9 (Design documents)

Large

Should be written before portal implementation; informs UI work

P2

Step 10 (Module-to-role map)

Small

Part of Step 9

P2

Step 12 (Troubleshooting)

Small

Collect from team knowledge; grow over time

P3

Step 14 (Screenshots)

Small

Blocked on portal routes

P3

Step 15 (CLI reference)

Small

Blocked on canopy-cli implementation

P3

Step 16 (Known issues)

Small

Start now; grow continuously

P3

Step 17 (User testing guide)

Medium

Needed before September UAT but not blocking development

P3

Step 18 (Nav update)

Small

Mechanical; do alongside each step

Verification

  1. cargo xtask check-docs — all mandatory docs exist and are non-empty

  2. Antora build (antora generate) — site builds without errors, all xrefs resolve

  3. Nav verification — every new page is reachable from navigation

  4. Link verification — no broken cross-references between pages

  5. Content review — each page has real content (not just template comments)

  6. Federal requirements — every regulation cited in code has an entry in federal-requirements.adoc

  7. Configuration reference — every ServiceSettings field has a corresponding env var entry

  8. Data models — every migration file has a corresponding table entry in data model pages

  9. State machines — every status enum in canopy-reference has a corresponding state diagram

Documentation Updates

  • .claude/CLAUDE.md — add new doc pages to required reading where appropriate

  • Service Catalog — cross-reference to API reference pages

  • CHANGELOG.adoc — entry under == Unreleased

Edit this page · default