Tiny Steps CMS

HIPAA-compliant practice management for four home health agencies in New York. Therapists document visits on their phones. Supervisors cosign remotely. The system tracks sixty credential types and locks anyone out the instant a critical one expires — before an auditor ever has to ask.

Built solo in 89 days. 515 commits, 196 production deployments, zero other contributors.

What it is

Tiny Steps is a full-stack clinical practice management platform for pediatric home health therapy. It manages the complete lifecycle from patient intake through visit documentation, supervisor cosigning, invoice generation, and payment reconciliation. Therapists use it daily on tablets and phones to document visits, capture signatures, and submit notes — replacing paper forms and spreadsheets across multiple agencies.

By the numbers

Monthly visit trend

2025-11  |||                                          3
2025-12  |||||||||                                    9
2026-01  ||||||||||||||||||||||||||||||||||||||||||  208
2026-02  ||||||||||||||||||||||||||||||||||||||||||  208
2026-03  |||||||||                                   44

System went live late 2025. Ramped to full production in January 2026 at 208 visits/month.

Architecture

                     Browser (React 19)
                            |
                  Next.js 16 App Router
                  /         |         \
            Server       Server       API
         Components      Actions     Routes (23)
                  \         |         /
                 Drizzle ORM (type-safe SQL)
                            |
                  Neon PostgreSQL (HIPAA BAA)
                            |
             28 tables / 45 migrations

      Tigris S3 ---- PDF Pipeline ---- Sentry
     (documents)   (@react-pdf +      (observability)
                    @cantoo/pdf-lib)

Key features

• Agency-polymorphic PDF pipeline — 13 fillable PDF templates across four agencies, each with different field layouts. A universal fill engine maps normalized data keys to per-template PDF field names, fills them via pdf-lib, then stamps drawn signatures at computed coordinates. Narrative notes generate PDFs via @react-pdf/renderer and merge with uploaded session notes into combined files.
• Credential lockout system — 60+ credential types with expiration tracking. Four critical credentials (Medical/Physical, PPD, Malpractice, CPR) trigger automatic login lockout when expired. PostgreSQL functions compute lockout state, with migration-level safeguards added after a production silent-failure incident.
• Supervision routing state machine — Notes from COTA / PTA / CFY therapists auto-route to their assigned supervisor for cosigning. The state machine enforces valid transitions (no_note → pending_review → co_signed → ready_for_billing) and prevents invalid state jumps.
• Per-agency invoice generation with renumbering — Each agency maintains its own invoice number sequence. Bulk generation packs visits into billing-cycle bundles (Sunday–Saturday), generates cover-sheet PDFs, and merges them with note PDFs into downloadable packages.
• SSN encryption at rest — AES-256-GCM encryption for Social Security numbers with a dedicated key. Encrypted fields are opaque in the database and decrypted only at the application layer for authorized views.
• 101-point audit trail — Every mutation (visit completion, note upload, credential update, invoice generation) writes a structured audit log entry. 3,909 entries in production. Full traceability for HIPAA compliance.
• Drawn signature capture and PDF stamping — Therapists sign on a canvas (signature_pad), the signature is captured as a PNG data URL, then stamped onto PDFs at precise coordinates. Signature events are tracked separately for co-signing workflows.
• Zod-validated server actions with discriminated unions — 165 server actions with input validation via Zod schemas, returning typed ActionResult<T> discriminated unions that force callers to handle both success and error paths at the type level.
• Role-scoped data access at every layer — Admins see everything. Therapists see only their assigned authorizations. Supervisors see their supervisees. Every query, server action, and API route enforces this boundary — not just the UI.
• Design system with automated enforcement — OKLCH color tokens, 4px spacing grid, shadcn-only components. A 15-check audit scanner runs as a pre-commit hook and blocks commits on violations (hardcoded colors, non-grid spacing, raw HTML elements, PHI exposure).

What makes it stand out

• Not a tutorial project. It runs in production with real therapists documenting real patient visits across four home health agencies.
• Solo-built in 89 days — 515 commits, 196 deployments, zero other contributors. Architecture, schema, PDF pipeline, deployment, monitoring — all one person.
• HIPAA-compliant infrastructure — Neon PostgreSQL with HIPAA BAA, SSN encryption at rest, PHI-aware audit scanning, role-scoped queries at every layer.
• 2,375 tests across unit, integration, and Playwright e2e suites covering admin / therapist / supervisor roles. The test suite is the deployment contract.
• Real financial processing — Actual invoices with dollar amounts flowing through the system. Not mock data.

Stack

Links

• Live: https://tiny-steps-cms.fly.dev