Privacy-first, offline-capable pain documentation for people living with chronic pain.

Pain Tracker helps people record pain, symptoms, treatments, and work impact, then export structured reports for clinicians, claims, and personal records. The app is local-first by default, with optional network integrations treated as explicit trust boundaries rather than the baseline architecture.

Current automated coverage includes 223 tests across the repository's tracked test files.

Live Demo · Case Study · Proof · Install · Privacy · Export Guide · Docs

• Why this exists
• Core features
• Trust boundaries
• Privacy model
• Architecture
• Getting started
• Configuration
• Testing and quality
• Security
• Roadmap
• Documentation
• Contributing
• License

Pain Tracker exists because standard health software often assumes stability: reliable housing, reliable internet, cognitive surplus, and safe disclosure conditions. This project is built around Protective Computing, a design discipline for systems that must remain legible and useful under pain, fatigue, interruption, and coercive conditions.

"I wrote software from motel rooms while homeless. Checking if CI passed while warming hands over a fire behind a gas station."

That experience shaped the architecture: local-first storage, user-controlled export, trauma-informed interaction design, and explicit trust boundaries for anything that reaches beyond the device.

• Full origin story: Coding Through Collapse—Why This App Forgets You Exist
• Protective Computing introduction: Architecting for Vulnerability: Introducing Protective Computing Core v1.0
• Canonical paper: Overton, K. (2026). Protective Computing Canon v1.0. DOI: 10.5281/zenodo.18887610

Deeper product detail lives in docs/product and the broader docs index at docs/README.md.

Pain Tracker is local-first by default.

The canonical PainTracker implementation artifact is the PainTracker Protective Computing Reference Packet v1.0. Legacy mappings are retained only as historical drafts until rewritten against the current repository, CI evidence, and claim badge taxonomy.

Protective Computing Specification v1.0 is a founder-authored normative design specification. Current implementation claims are conformance claims, not certification. A system may be described as self-attested, repo backed, CI backed, externally reviewed, or certified only according to the published proof badge taxonomy.

PainTracker is a candidate reference implementation with a public reference packet, explicit limitations, and bounded evidence anchors. It is not certified. Its current posture is Level 2 to Level 3 alignment where evidence exists, with unresolved gaps in active-coercion resistance, accessibility-complete degraded mode, and external review.

For trust and reversibility framing, see docs/trust/paintracker-protective-computing-reference-packet-v1.0.md, docs/trust/README.md, and SECURITY_INVARIANTS.md.

• Local-first by default: entries stay on the device unless the user explicitly exports them.
• User-controlled exports: reports are generated on demand for clinicians, claims, or personal records.
• Optional integrations require configuration: network-dependent features are separate trust boundaries, not baseline requirements.
• No compliance claims: the project documents privacy-aligned controls and limits without overstating legal or regulatory guarantees.

Start with PRIVACY.md, SECURITY.md, and docs/SAFETY_PLAN.md.

Pain Tracker is a React and TypeScript application using Zustand, Zod, IndexedDB, and export pipelines designed around local durability and auditability.

flowchart LR
    A[User input] --> B[Zod validation]
    B --> C[Zustand state update]
    C --> D[Local persistence]
    D --> E[Local analytics]
    D --> F[User-controlled export]
    G[Optional network integrations] -. explicit configuration .-> C

• Architecture overview: docs/engineering/ARCHITECTURE.md
• Deep dive: docs/engineering/ARCHITECTURE_DEEP_DIVE.md
• Data flow diagrams: docs/diagrams/README.md

Pain Tracker is developed primarily on Windows with PowerShell.

git clone https://github.com/CrisisCore-Systems/pain-tracker.git
Set-Location .\pain-tracker
npm install
npm run dev

Open the local app at the Vite URL shown in the terminal.

Core verification commands:

npm run test:coverage
npm run build
npm run preview

For a fuller setup path, see docs/user-guide/INSTALL.md, QUICKSTART.md, and docs/engineering/DEVELOPER_COMMANDS.md.

• Validation UI flags: VITE_REACT_APP_ENABLE_VALIDATION and VITE_ENABLE_VALIDATION_TECH
• Analytics subsystem: VITE_ENABLE_ANALYTICS defaults to disabled unless explicitly set to true
• Optional local API and clinic paths: see QUICKSTART.md and docs/engineering/INTEGRATION_GUIDE.md
• Historical billing docs: archived under docs/archive/saas and not part of the supported production path today

Primary quality gates:

npm run check:quick
npm run check
npm run security-full

Focused commands and workflows live in docs/engineering/DEVELOPER_COMMANDS.md. Current automated metrics are published through the badges at the top of this README.

• Local-first storage and selective encryption helpers for sensitive data
• CSP, security scans, secret scanning, and trust-claims validation in repo workflows
• Audit/event logging patterns designed to avoid reconstructing sensitive user content
• Private vulnerability reporting guidance in SECURITY.md

Start with SECURITY.md, SECURITY_INVARIANTS.md, and docs/trust/threat-model.md.

Current 2026 priorities:

1. Strengthen local-only analytics and visualizations without adding surveillance surfaces.
2. Expand export and reporting defensibility for clinician and WorkSafeBC workflows.
3. Improve degraded-mode resilience, especially around persistence, recovery, and PWA behavior.
4. Tighten trust-boundary documentation for optional integrations and deployment-specific backend paths.
5. Continue accessibility and trauma-informed UX hardening against the WCAG 2.2 AA target.

Longer-form planning lives under docs/planning and docs/index.

Use the docs hub for longform material: docs/README.md

• User docs: docs/user-guide/INSTALL.md, docs/user-guide/FAQ.md, docs/user-guide/EXPORT_DATA.md
• Engineering docs: docs/engineering/ARCHITECTURE.md, docs/engineering/DEVELOPER_COMMANDS.md
• Trust and security docs: docs/trust/README.md, SECURITY.md, SECURITY_INVARIANTS.md
• Product and research docs: docs/product, docs/papers
• Screenshot and marketing references: docs/marketing/SCREENSHOT_PORTFOLIO.md

Contributions should preserve local authority, exposure minimization, reversibility, degraded-mode resilience, and truthful documentation.

• Contribution guide: CONTRIBUTING.md
• Repo operating rules for agents and reviewers: AGENTS.md
• Commit conventions and developer workflows: docs/engineering/DEVELOPER_COMMANDS.md

This project is licensed under the MIT License. See LICENSE.