Phylax

Your local-first, zero-knowledge living health profile.

Live demo: https://astrapi69.github.io/phylax/ (install as a PWA via your browser's address bar)

User documentation: https://astrapi69.github.io/phylax-docs/ (Iteration 1 complete; DE+EN parallel content covering Getting Started, Daily Use, Backup, FAQ and Background)

What is Phylax

Phylax (Greek: phylax, "guardian") is a personal, data-sovereign health platform built as a Progressive Web App. All data stays on your device, encrypted with a master password you choose. There is no backend, no cloud, no telemetry, and no data collection.

The core artifact is a living medical profile: a versioned, structured document where you record observations about your health, grouped by theme (for example "Shoulder", "Nutrition", "Blood pressure"). Each observation has three facets: what happened (fact), what recurs (pattern), and what you decided to do about it (self-regulation). The profile also tracks lab values, supplements, and open questions for your next doctor visit.

Phylax supports AI-guided profile creation: you provide fragments (lab photos, medication names, verbal observations), and an AI structures them into your profile using your own API key. Multiple providers are supported - Anthropic, OpenAI, Google, Mistral, plus local models via LM Studio or Ollama (see ADR-0019). The AI operates under a strict contract: it structures, it does not diagnose. You can also enter data manually or paste markdown from an external AI session.

The name comes from the Greek phylax (guardian). Phylax is not a doctor, not a database, but a guardian of your health narrative.

Who is Phylax for

• Privacy-conscious individuals tracking their own health profile
• Caregivers tracking dependents (elderly parent with dementia, child)
• Anyone preparing for doctor visits with structured, fact-based notes
• Developers interested in local-first, zero-backend PWA architecture

Phylax is primarily designed for German-speaking users; the UI ships bilingual (German + English) with auto-detection and a manual override. The developer documentation (this README, ADRs) is in English; the user- facing concept and roadmap docs are in German.

Screenshots

Features

• Encrypted local storage: AES-256-GCM per record, PBKDF2-SHA256 with 1.2 million iterations, in-memory master key only (never written to disk)
• Living health profile: observations grouped by theme, lab values, supplements, open points, timeline entries, profile versioning
• Markdown import: tolerant parser for the "Lebende Gesundheit" format, with an AI-assisted cleanup fallback when the input does not match
• Read-only views per entity type with alphabetical and recent-first sorting
• AI assistant (optional, bring your own API key for any supported provider):
  • Multi-provider: Anthropic, OpenAI, Google, Mistral, plus local LM Studio / Ollama / custom OpenAI-compatible endpoints (ADR-0019)
  • Structuring partner only; never diagnoses, never interprets lab values
  • Share profile context into the chat without losing messages between turns
  • Commit preview with diff view and field-level merge
  • Guided session mode that walks three profile sections systematically
  • Parser fallback: reformat unparseable markdown via one-click cleanup
• Document import (Phase 4b): upload lab reports / doctor letters / ePA exports; the AI classifies and extracts structured entries with provenance tracking back to the source document
• Multi-format export (Phase 5): PDF, Markdown, CSV with date-range and theme filters and an optional linked-documents appendix
• Backup and restore (Phase 6): encrypted vault export to a single .phylax file; round-trip restore preserves all entities and provenance
• Change master password (P-06, ADR-0018): atomic re-encryption of the full vault under a new key; key swap bounded in memory
• Cross-feature search (P-22): instant search across observations, lab values, supplements, open points, and documents
• Progressive Web App: installable, works offline, silent background service-worker updates (BUG-01)
• Accessibility: WCAG 2.1 AA via axe-core checks in the production E2E suite
• Dark mode with system-preference detection
• Bilingual UI: German + English at runtime with auto-detection and a manual override (I18N-02-e)

Origin

Phylax implements the "Living Health" concept by Asterios Raptis, a four-part Medium series arguing that health is a user-led process, not a state managed by others.

English:

• Part 1: Living Health: From Patient to Partner
• Part 2: Living Health in Practice
• Parts 3-4: Translation in progress

Original German:

• Lebende Gesundheit - Die Serie

The four parts cover:

1. Concept: health as a user-led process, not a managed state
2. Self-application: observe, pattern, self-regulate
3. Caregiver profiles (elderly parent, dependent child)
4. AI as a structuring partner, not a diagnostician

Phylax is the practical implementation: a tool for carrying out steps 2-4 in daily life.

Not a medical device

Phylax is a personal data management tool. It does not provide medical advice, diagnosis, or treatment recommendations.

AI in Phylax structures, it does not diagnose. The AI organizes what you bring in. It does not interpret your health data, recommend treatments, or replace professional medical judgment.

If you are experiencing a medical emergency, contact your doctor or call emergency services immediately.

Phylax helps you organize and store your own health records. Nothing more.

Security

Phylax encrypts all health data before writing it to the browser's IndexedDB:

• AES-256-GCM encryption per record, with a unique 12-byte IV per write
• PBKDF2-SHA256 key derivation with 1.2 million iterations from your master password
• In-memory key only: the derived key is never written to disk. It lives in memory while the app is unlocked and is cleared on lock or page close.
• Auto-lock after 5 minutes of inactivity (configurable)
• No network calls except user-initiated AI requests with the user's own API key

Phylax protects against:

• An attacker reading your IndexedDB without the master password (encrypted at rest)
• Network eavesdropping (no network used; everything is local)
• Cloud provider access (no cloud)
• App developer access (no telemetry, no remote management)

Phylax does NOT protect against:

• Keyloggers or malware on your device
• Malware reading your screen while Phylax is unlocked
• Physical coercion to reveal your master password
• A forgotten master password (no recovery; data is lost)
• A compromised browser or operating system

For the full security model, see docs/CONCEPT.md.

Privacy summary

• Nothing leaves your device unless you explicitly use the AI features.
• AI requests go directly from your browser to the provider you choose (Anthropic, OpenAI, Google, Mistral, LM Studio, Ollama, or a custom OpenAI-compatible endpoint) using your own API key. Each provider has its own retention and training policy; Phylax surfaces the relevant disclaimer in-app at the point of provider selection. Local providers (LM Studio, Ollama) keep AI traffic on your own machine.
• Your provider account is yours, not Phylax's. You can audit usage and revoke each key directly in the provider's console at any time.
• No telemetry, no analytics, no error reporting services.

The in-app disclaimer (shown on first AI activation) and the "Datenschutz beim KI-Chat" popover (chat header, settings section) carry the same information in German at the point of use.

Project status

Phylax v1.0.0 shipped 2026-04-18. Subsequent work is post-1.0.0 polish plus a few new feature phases. Closed phases:

• Phase 1 - Foundation: crypto, storage, onboarding, auto-lock, PWA
• Phase 2 - Profile: domain model, repositories, profile versioning, manual-entry CRUD (O-10..O-19), shared modal primitive (O-20)
• Phase 2b - Import: markdown parser, import pipeline, UI; IM-04 auto-version-entry; IM-05 per-type replace toggles plus Option B merge
• Phase 2c - Views: read-only views for observations, lab values, supplements, open points, timeline, profile overview
• Phase 2d - Theming: dark mode with system-preference detection
• Phase 3 - AI-Guided Input: chat UI, guided session, commit preview, parser fallback
• Phase 4 - Documents: D-01..D-10 attached-document storage and viewer
• Phase 4b - ePA Import: IMP-01..06 document classification and structured-entry extraction with provenance
• Phase 5 - Export: X-01..X-08 Markdown / PDF / CSV with date-range, theme filter, and linked-documents appendix
• Phase 6 - Backup: B-01..B-04, B-06, B-07 encrypted vault round-trip
• Phase ONB: onboarding UX restructure
• Phase S: donation integration
• Multi-AI-Provider (AIP-01..05, ADR-0019): seven preset providers plus custom OpenAI-compatible endpoints
• Infrastructure (I-series, DEPS-01..03): React 19 (ADR-0021), TypeScript 6, Vite 7 / Vitest 4, Tailwind 4, Node 24, CI coverage policy

In progress (Phase 7 polish): manual-entry forms, error boundary (P-09), inline document delete (P-16), search (P-22), license footer (P-12), Change Master Password (P-06, ADR-0018).

Deferred: Phase 8 multi-profile (deprioritised 2026-05-01), Phase 9 derived plans, P-11 ES/FR/EL translations.

Current test counts: 2632 unit tests across 279 files, 0 axe violations. Bundle budgets: 350 KB main JS, 380 KB total JS+CSS gzipped (ADR-0015). Mutation thresholds per-module (crypto 95%, repositories 95%, parser 55%, import 75%; see .claude/rules/quality-checks.md).

See docs/ROADMAP.md for the full task breakdown, CHANGELOG.md for the release history, and docs/audits/current-coverage.md for the latest coverage audit.

Quick start

Try it live

Open https://astrapi69.github.io/phylax/ in Chrome, Edge, or any Chromium-based browser. Click "Install Phylax" from the address bar (or three-dot menu) to add it to your home screen / app drawer. Phylax runs entirely in the browser and works offline after the first visit.

Run from source

Requires Node.js 24 or later. CI and .nvmrc both pin Node 24. If you use nvm, nvm use picks up the .nvmrc version.

git clone https://github.com/astrapi69/phylax.git
cd phylax
npm install
make dev          # http://localhost:6173

On first visit, the app walks you through creating a master password. After that, the profile view is your home; import an existing markdown profile or start by adding observations manually.

Build for production:

make build
make preview      # http://localhost:6174

Install as a PWA

Once the production build is served (or once a deployed version is available), the browser will offer "Install Phylax" in the URL bar or via the three-dot menu. After install, Phylax runs offline and appears as a standalone app on the home screen or app drawer.

Run tests

make test                 # Unit tests (2632 tests)
make test-e2e             # E2E tests against dev server
make test-e2e-production  # E2E tests against production build
make test-bundle-size     # Production bundle vs size-limit budgets
make ci-local-full        # Everything CI runs

Run make help to see all available targets.

AI features (optional)

AI features are opt-in and require your own API key for one of the supported providers (ADR-0019):

• Cloud providers: Anthropic, OpenAI, Google (Gemini), Mistral
• Local providers: LM Studio, Ollama
• Any custom OpenAI-compatible endpoint

1. Get a key (or run a local model). For cloud providers, generate a key in the provider's console.
2. In Phylax: Einstellungen -> KI-Assistent -> Anbieter verwalten -> add a provider, paste the key, accept the per-provider disclaimer, activate.
3. Navigate to /chat and start a conversation. Use "Profil teilen" to let the AI see your current profile context (ephemeral, not persisted).
4. Use "Gefuehrte Sitzung starten" for a guided walkthrough of three profile sections (observations, supplements, open points).
5. The active provider can be switched at any time via the same wizard.

The assistant is a structuring partner, not a diagnostician. Each provider has its own retention and training policy; the in-app disclaimer surfaces the relevant text at the point of provider selection.

Change master password

Settings -> Sicherheit -> Master-Passwort ändern triggers an atomic re-encryption of the entire vault under the new key (P-06, ADR-0018). The old key is dropped from memory once the new key is committed; partial failure restores the previous state.

Development

Test patterns

• State-holding modules (keyStore): use vi.resetModules() + dynamic import() in beforeEach to get a fresh module instance per test.
• PBKDF2 + fake timers: call vi.useFakeTimers() AFTER async setup that involves PBKDF2. Key derivation at 1.2M iterations takes ~420ms of real wall time and will hang under fake timers.
• IndexedDB cleanup in Playwright: page.evaluate(() => indexedDB.deleteDatabase('phylax')) before each E2E test.
• Auth test setup: setupCompletedOnboarding(password) in src/db/test-helpers.ts creates a meta row and leaves the key store locked, ready for unlock tests.
• Per-module coverage thresholds are enforced in CI, not locally (see .claude/rules/quality-checks.md).

PWA development caveats

• In dev mode, the service worker may cache stale assets. Clear via chrome://serviceworker-internals (unregister the SW) or use an incognito window.
• Offline caching only works in production builds. Use make test-e2e-production to verify.
• devOptions.type: 'module' is enabled for modern dev SW support.

Icon regeneration

Icons are generated from SVG sources via @resvg/resvg-js:

make icons        # Reads public/icons/source.svg, writes all PWA icon sizes

Architecture

Phylax uses a three-layer architecture enforced by ESLint:

UI layer (React 19 + TypeScript + Tailwind + Vite): functional components, hooks, feature folders. Never imports crypto.subtle or Dexie directly.

Domain layer (pure TypeScript): types, validation, business logic. No React, no Dexie. Defines interfaces; implementations are injected from the storage layer.

Storage layer (Dexie + Web Crypto): IndexedDB schema, encrypted repositories. Every record is stored as { id, profileId, createdAt, updatedAt, payload } where payload is a single AES-256-GCM encrypted blob. Only structural metadata is plaintext; content fields are filtered in-memory after decryption.

The app is a PWA via vite-plugin-pwa with Workbox precaching. All assets are bundled; no external network calls at runtime except user-initiated AI requests.

src/
  crypto/          Encryption and key derivation (only place using crypto.subtle)
  db/              Dexie schema and repositories (only place importing Dexie)
  domain/          Pure business logic, validation, types
  features/        React feature folders (onboarding, profile, ai-chat, ai-config, ...)
  router/          Route definitions and auth guards
  ui/              Shared UI components
  i18n/            Translations (DE, EN)
  lib/             Small utilities
  pwa/             Service worker registration
  test/            Shared test setup

Further reading

• docs/CONCEPT.md: living health profile vision, data model, AI role, security model (German)
• docs/ROADMAP.md: task list with IDs, grouped by phase, progress checkboxes
• docs/decisions/: architectural decision records (ADRs)
• docs/audits/: coverage audits and state reports
• .claude/rules/: architecture rules, coding standards, quality checks

Contributing

Phylax is developed by a single person. For v1.0.0, pull requests are deferred in favor of stabilization, but the following are welcome:

• Bug reports via GitHub Issues
• Feature feedback, especially from users of similar tools
• Security reports (responsible disclosure; a SECURITY.md will follow)
• Translation review for German UI strings

Pull requests will be accepted after v1.0.0 ships. See .claude/rules/ for the architectural and coding standards that contributions will need to follow.

Support the project

Phylax is developed by a single person as an open-source project. If you find it useful, consider supporting its continued development.

See DONATE.md for options (Liberapay, GitHub Sponsors, Ko-fi, PayPal). Liberapay is the recommended path: FOSS-friendly, no platform fees, no account required for the donor.

License

MIT

Acknowledgments

• The "Lebende Gesundheit" concept by Asterios Raptis, implemented here in code form
• React, Vite, Dexie.js, Tailwind CSS, Vitest, Playwright
• @axe-core/playwright for accessibility testing
• @resvg/resvg-js for icon generation
• The AI providers Phylax supports as optional structuring partners: Anthropic Claude, OpenAI, Google Gemini, Mistral, LM Studio, Ollama