DriverPath — Agent Instructions

This file is auto-loaded by Codex (OpenAI) and any other agents that read AGENTS.md.

• Claude Code → see CLAUDE.md
• Antigravity IDE → see GEMINI.md (auto-loaded by that IDE)
• Replit AI → see replit.md

Project Summary

DriverPath is a HIPAA-compliant SaaS platform for physical therapists. It enables clinicians to curate evidence-based patient education, conduct assessments, and track engagement.

Stack: React 19 + TypeScript (frontend) / Node.js + Express + PostgreSQL (backend) / Drizzle ORM

Session Start Protocol

Before writing any code, complete these steps:

1. Read docs/Agent_guide.md — single entry point for all project documentation
2. Read docs/agent-sessions/ACTIVE_SESSION.md — check for in-progress work
3. Review recent commits to orient yourself: git log --oneline -10
4. Read the specific GitHub issue you are solving

Available Commands

# Development
make dev                      # Start server (port 5000)
make setup                    # Install dependencies
make migrate                  # Run DB migrations

# Testing
make test                     # Run all tests
./scripts/test.sh smoke       # Fast smoke tests (run before marking work done)
./scripts/test.sh feature X   # Test specific feature
./scripts/test.sh full        # Full suite (run before PRs)

# Quality
npm run check                 # TypeScript type check
make build                    # Production build

Architecture: 5-Layer Domain-Driven Design

Full specification: docs/architecture/ARCHITECTURE.md

HTTP Request
    ↓
[Routes]         server/routes/           — Validate input (Zod), route to app services
    ↓
[Application]    server/application/      — Orchestrate multi-step workflows
    ↓
[Domain]         server/domain/           — Pure business logic (no DB, no HTTP)
[Infrastructure] server/infrastructure/   — External APIs (email, Stripe, Contentful, PDF)
    ↓
[Storage]        server/storage.ts        — Database access (Drizzle ORM)

Layer Rules (enforced — never bypass)

• Routes call application services or storage for simple operations — never directly call domain from routes for complex flows
• Domain services are pure: no database access, no external HTTP calls, no side effects
• Infrastructure services wrap external APIs and translate errors
• Application services own transactions; domain services do not

Import Conventions

Use barrel exports for clean imports:

// Correct
import { createSecureAccessCode } from "../domain/messaging";
import { sendContentEmailFlow } from "../application/messaging";
import { sendContentEmail } from "../infrastructure/email";

// Avoid (unless necessary)
import { createSecureAccessCode } from "../domain/messaging/access-code.service";

Testing Requirements

Follow the decision tree in docs/developer/DEVELOPMENT_WORKFLOW.md:

Always run ./scripts/test.sh smoke before declaring any task complete.

Data-testid Conventions

Required on all interactive UI elements:

• Buttons: data-testid="button-[action]" (e.g., button-submit, button-cancel)
• Inputs: data-testid="input-[field]" (e.g., input-email)
• Cards: data-testid="card-[type]-[id]"
• Modals: data-testid="modal-[name]"

Documentation to Update

HIPAA Compliance Rules

These are non-negotiable and cannot be skipped:

1. All PHI access must be logged via logClinicianAction() in server/infrastructure/audit/
2. Never expose access codes in API responses, logs, or console output
3. Use PBKDF2 for access code hashing and scrypt for password hashing (never MD5, SHA1, or plain bcrypt)
4. Patient sessions must expire after 24 hours — do not modify this timeout
5. Feature-flag-gated routes must use requireFeatureFlag middleware

Actions That Require Human Approval

Stop and ask the human before taking any of these actions:

• Creating new database tables or modifying schema (shared/schema.ts, migrations/)
• Adding or removing environment variables
• Modifying .github/workflows/ (CI/CD)
• Changing authentication, authorization, or session logic
• Adding new npm dependencies
• Deleting files, branches, or migrations

Session End: Leave Breadcrumbs

Before ending your session, update docs/agent-sessions/ACTIVE_SESSION.md. Use the template at docs/agent-framework/SESSION_HANDOFF_TEMPLATE.md.

The next agent depends on this file to pick up where you left off.

Key File Locations