Modernize ClearPath for safer, maintainable clinical drafting

[rdsciv]

Context

This PR turns the original ClearPath MVP into a safer, better documented, and more maintainable clinical-documentation prototype without expanding its core product scope. The repository had a sound small-app foundation, but the review found several issues that had accumulated around a single initial implementation:

• the ASAM Mapper encoded the Third Edition dimension structure even though the Fourth Edition changed the six adult dimensions;
• Next.js 16.1.6 was affected by multiple published security advisories;
• the three API routes and three client pages duplicated their streaming logic;
• the browser's 5,000-character cap was not enforced on the server;
• streamed UTF-8 text could be corrupted when a multibyte character crossed a chunk boundary;
• malformed JSON, missing configuration, upstream failures, and cancellation were not handled consistently;
• the UI and repository did not explain the clinical, privacy, or compliance boundaries of sending text to an external model;
• the production build depended on fetching Google Fonts; and
• the project had no README, automated tests, or CI.

What changed

Align the clinical framework with current ASAM terminology

• Reworked the ASAM Mapper prompt around the adult dimensions in The ASAM Criteria, Fourth Edition:
  1. Intoxication, Withdrawal, and Addiction Medications
  2. Biomedical Conditions
  3. Psychiatric and Cognitive Conditions
  4. Substance Use-Related Risks
  5. Recovery Environment Interactions
  6. Person-Centered Considerations
• Removed Readiness to Change as a standalone dimension and treated readiness/motivation as an integrated consideration.
• Added explicit prompt boundaries against diagnosis, risk-rating assignment, level-of-care recommendations, and treating documentation coverage as proof of clinical adequacy.
• Updated the ASAM badge labels, assessment placeholder, internal project guidance, and public documentation to match.

Consolidate and harden server-side streaming

• Replaced three nearly identical route implementations with thin adapters over one shared createStreamingToolResponse helper.
• Added shared server-side validation for payload shape and trimmed input length (50–5,000 characters).
• Added explicit responses for malformed JSON (400), invalid input (400), missing API configuration (503), and pre-stream provider failures (502).
• Added Cache-Control: no-store, explicit text content types, and request cancellation propagation.
• Made the Anthropic client lazy and server-only so a missing key does not fail module initialization.
• Made the model configurable through ANTHROPIC_MODEL, with claude-sonnet-5 as the default.
• Avoided logging submitted text or detailed provider errors.

Fix client streaming and improve usability

• Replaced three duplicated fetch/read loops with a shared useStreamingTool hook.
• Decode chunks with TextDecoder.decode(..., { stream: true }) and flush the decoder at completion, preventing split multibyte characters from becoming replacement glyphs.
• Abort active requests on navigation/unmount and expose a visible Stop control.
• Preserve partial results after cancellation.
• Add resilient clipboard error handling and disable copying while a response is still streaming.

Add privacy, safety, and accessibility guardrails

• Added a visible notice to every tool asking users to de-identify text and verify results with current criteria, policy, supervision, and clinical judgment.
• Added a concise disclaimer to the home page.
• Associated labels, textareas, and help text correctly; surfaced aria-invalid, aria-current, aria-busy, and meaningful labels for generated results and ASAM badges.
• Improved navigation behavior on narrow screens.
• Added baseline security headers and disabled the framework identification header.

Modernize dependencies and build behavior

• Upgraded Next.js from 16.1.6 to 16.2.10 and eslint-config-next in lockstep.
• Upgraded the Anthropic TypeScript SDK from 0.78.0 to 0.111.0.
• Added narrow transitive overrides for patched brace-expansion and PostCSS releases after verifying compatibility through lint, types, tests, and a production build.
• Added Vitest 4.1.10.
• Removed the runtime Google Fonts fetch and used a system font stack, making local and CI builds deterministic and avoiding an unnecessary third-party browser request.
• Added a Node.js engine floor and reusable typecheck, test, and check scripts.

Document the project and automate verification

• Added an extensive README covering:
  • purpose and feature behavior;
  • Fourth Edition terminology and official references;
  • data flow and architecture;
  • local setup and environment variables;
  • API contracts and response behavior;
  • privacy, security, clinical-safety, and compliance boundaries;
  • deployment requirements, limitations, contribution guidance, and roadmap ideas;
  • ASAM affiliation/trademark clarification and the repository's current license status.
• Added a safe .env.example and adjusted .gitignore to keep it tracked.
• Added GitHub Actions CI for install, lint, type-check, unit tests, and production build.
• Added 10 unit tests covering input boundaries, malformed payloads, completed ASAM status parsing, partial streamed output, and section-boundary isolation.

User and developer impact

Users get current Fourth Edition labels, clearer safety expectations, better mobile/accessibility behavior, a cancel control, and more reliable streamed text. Developers get one request path and one client streaming path instead of maintaining six copies, along with documented setup, tests, CI, configurable models, and deterministic builds.

No database, authentication system, EHR integration, or persistence layer was introduced.

Validation

• npm run lint — passed
• npm run typecheck — passed
• npm test — 2 files / 10 tests passed
• npm run build — passed with all pages and API routes generated on Next.js 16.2.10
• npm audit — 0 vulnerabilities after the dependency update and scoped overrides
• git diff --check — passed
• Live development-server checks:
  • /, /treatment-plan, /asam-mapper, and /doc-reviewer returned 200 with HTML content
  • configured security headers were present
  • malformed JSON returned 400
  • short input returned 400
  • valid input without ANTHROPIC_API_KEY returned 503

Not run: a live Anthropic generation, because no API key was placed in the review environment. Screenshot-level browser verification was also unavailable in the review session; compilation and live HTTP checks were completed instead.

Important boundaries and follow-up work

This remains an educational prototype. It is not ready for identifiable clinical data. Before real-world deployment, the project still needs organizational clinical/privacy/security review plus authentication, authorization, rate limiting, abuse controls, monitoring, a logging and retention policy, vendor agreements where required, and clinician-led prompt/output evaluations.

The model still returns plain text shaped by prompt instructions. A valuable next step is structured output with schema validation, which would remove the ASAM badge parser's dependence on Markdown headings and status phrases.

Suggested review order

1. README.md for intended scope and safety boundaries.
2. src/lib/prompts.ts and src/lib/asam.ts for the Fourth Edition update.
3. src/lib/streaming-tool-route.ts and src/hooks/use-streaming-tool.ts for the shared request path.
4. tests/ and .github/workflows/ci.yml for verification coverage.
5. package.json and package-lock.json for the dependency/security update.