ADR-008: Applicant Portal Architecture (Dioxus Fullstack)

The portal is a BFF (Backend for Frontend) that:

Applicants begin with an anonymous session. No account creation required to start an application. The session is PostgreSQL-backed (tower-sessions-sqlx-store, never MemoryStore) with a 30-minute sliding TTL.

On form submission, the system generates a reference number (format: CANOPY-YYYYMMDD-XXXXXXXX). The applicant receives this number via the portal and, if provided, via email or SMS. The reference number + date of birth serves as the authentication pair for returning to check status, upload documents, or file appeals.

No Keycloak account is created for applicants. Keycloak is reserved for workers and system operators. Applicant identity verification happens through the eligibility determination process, not through an identity provider.

Rationale: requiring account creation is a barrier. Many SNAP applicants lack stable email addresses. The reference-number model mirrors how paper applications work today — the applicant receives a case number and calls to check status.

Reference number + DOB verification is handled by a dedicated server function that validates against canopy-applications. Failed attempts are rate-limited (30 per 60 seconds per client, matching IMTN’s pattern).

The portal uses Project Fluent (.ftl files) for all user-visible strings. No English text is hardcoded in Rust source or templates.

Locale negotiation (in priority order):

Initial languages: English (en) and Spanish (es). Georgia’s SNAP population is approximately 8% Spanish-speaking. Additional languages added by creating new .ftl files — no code changes required.

SSR i18n: Server functions resolve the locale from the request context and load the appropriate Fluent bundle. Translated strings are embedded in the SSR HTML. WASM hydration picks up the same locale from a <meta> tag or data- attribute.

Fluent file organization:

Applicants upload verification documents (pay stubs, ID, utility bills) via the portal. Files are stored in S3-compatible storage (Garage in devstack) via canopy-store.

Restrictions:

The portal meets WCAG 2.1 AA. This is a legal requirement under Section 508, not a best-effort goal.

Mandatory patterns (proven in IMTN):

Testing:

CSP (Content Security Policy):

Per-response random nonce for all <script> tags. No 'unsafe-inline' or 'unsafe-eval' for scripts. 'wasm-unsafe-eval' required for WASM instantiation (standard necessity). Style: 'unsafe-inline' permitted (Dioxus may inject inline styles; mitigated by nonce enforcement on scripts).

The portal implements the ACA §1413 single-streamlined application. Applicants fill out one form. The system determines eligibility for all applicable programs (SNAP, TANF, Medicaid/CHIP, CAPS, WIC) from a single submission.

Form sections:

Each section is a Dioxus component with client-side validation and server-side validation on submit. Draft data is saved to the server on section completion (not just localStorage) so applicants can resume from any device.

Phase 1 (UAT): Web browser (SSR + WASM). Responsive design covers mobile, tablet, and desktop.

Phase 2 (post-UAT): DHS field office kiosk. Same Dioxus codebase compiled to a native desktop target (Dioxus desktop renderer). Kiosk mode: no URL bar, no navigation, session auto-expires. Offline-capable: Service Worker caches the application shell; form data syncs when connectivity resumes.

Phase 3 (future): Mobile app. Same Dioxus codebase compiled to native mobile targets via Dioxus mobile renderer. Document upload uses device camera directly. Push notifications for determination results.

The single-codebase-multiple-targets story is the primary reason for choosing Dioxus over Askama. Askama renders HTML on the server — it cannot compile to desktop or mobile.

canopy-web (worker portal) remains Askama + htmx + Alpine.js. canopy-portal (applicant portal) is Dioxus fullstack. They are separate binaries with separate sessions, separate Orchard theme variants, and separate deployment profiles.

Shared infrastructure:

The two portals do not share components, templates, or rendering code. This is intentional — their interaction patterns are different enough that forcing shared components would compromise both.

Proven pattern, same as the worker portal. Rejected because:

Would provide excellent component ecosystem and SSR. Rejected because:

Rust WASM framework with fine-grained reactivity and SSR. Not selected because:

Add Service Worker and manifest.json to the Dioxus web app for offline support and mobile installability. This is planned as a Phase 2 enhancement, not an alternative architecture. The Dioxus fullstack approach accommodates PWA features without architectural changes.

Supersedes: the "Session Model" reference-number format and the "Authentication" reference-number-plus-date-of-birth pair.

Decision. The returning-applicant authentication pair is an Application ID plus a Passcode:

Date of birth is never used as an authentication factor.

Rationale. The applicant-portal threat model is intimate-threat-dominant: the most likely adversary is a household member, former partner, or caregiver who already knows the applicant’s date of birth, address, and case details. A date of birth is therefore not a secret and cannot serve as an authentication factor. A system-generated random passcode is unknown to such an adversary and is independently revocable. The HH--prefixed Application ID and the three-word-plus-digits passcode also read aloud and transcribe more reliably than an opaque alphanumeric string — important for applicants assisted over the phone or at a kiosk. This format is the contract locked in the canopy-portal design handoff (design reference).

+ NOTE: The passcode format is superseded by Amendment 3 — Passcode format: all-digit (now NNNN-NNNN-NNNN); see the Amendments section.

Consequences. The brute-force / rate-limiting protections in the "Authentication" section apply to the Passcode, not to a date of birth. The lost-credential recovery flow (a later plan deliverable) issues a new passcode rather than disclosing the existing one, and is gated by a delay + side-channel notification + kill-switch per the handoff’s intimate-threat mitigations.

Supersedes: the "Accessibility › CSP" allowance of 'unsafe-inline' for styles.

Decision. 'wasm-unsafe-eval' is the only unsafe directive permitted in the portal’s Content Security Policy. Specifically:

Rationale. Inline-style allowances widen the XSS surface and are inconsistent with the strict, Kerckhoffs-aligned security baseline the portal is held to (see the project security baseline). The original allowance assumed Dioxus must inject inline styles; that assumption is the subject of a build-time spike (see Consequences).

Consequences. Whether Dioxus 0.7 can render with zero inline-style emission is verified by a CSP + routing spike before any UI components are built — a hard gate: no component emission proceeds until the spike proves zero-inline-style output or an explicit hash-based style-src fallback (enumerated style hashes, still never 'unsafe-inline') is ratified. This spike and its outcome are tracked at #630.

Supersedes the passcode half of Amendment 1 — Credential format. The passcode changes from word-word-word-NN (three wordlist words plus two digits) to NNNN-NNNN-NNNN — twelve digits in three dash-separated groups of four, drawn as a single uniform CSPRNG value over 0–999999999999 (leading zeros valid; the dashes are cosmetic). Entropy is ~40 bits (10^12 ≈ 39.9 bits), matching the prior target.

Rationale: the constituency includes functionally illiterate applicants, and the passcode is consumed by read-aloud (kiosk/assisted), IVR, and screen-reader/TTS channels. An all-digit passcode (a) needs only number recognition — more universal than word literacy and language-independent (no English/Spanish wordlists to curate or review); (b) carries zero stigma risk — wordlist passcodes can assign distressing words (e.g. pauper, cancer, corpse) to vulnerable applicants; (c) is keypad-enterable via DTMF on the IVR, eliminating any speech-recognition requirement; and (d) has no homophones, so it transcribes unambiguously through TTS and over the phone. The Application ID remains HH-[a-f0-9]{8} — its hex letters now also serve to visually distinguish the ID from the all-digit passcode, reducing field-swap errors. Generation MUST be a uniform CSPRNG draw over the full range (no leading-zero avoidance, no weak RNG), or entropy is silently lost. The profanity-screened wordlist (and its English/Spanish bundles) is no longer needed and is removed from scope.

This supersedes Amendment 1’s passcode format only; the HH-… Application ID, the rule that date of birth is never an authentication factor, and the intimate-threat rationale are unchanged.

Two clauses above are superseded by ADR-042: