Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (60 loc) · 2.93 KB

CLAUDE.md

File metadata and controls

80 lines (60 loc) · 2.93 KB

Heim

Principles

  • Security and GDPR compliance are hard requirements, not afterthoughts.
    • No PII in cleartext — use forgettable payloads with crypto shredding (see docs/database.md).
    • events.metadata and audit_log.detail must never contain PII.
    • Every new field that stores personal data needs an explicit plan for right-to-erasure.
    • Validate and sanitize at system boundaries (user input, external APIs).
    • Secrets (MEK, HMAC keys) must stay out of code and config files — use env vars or KMS.
  • Good developer experience and ergonomics is a key priority.
  • Prefer small interfaces over deep hierarchies. A new capability should ideally mean a new implementation of an existing interface, not a change to shared abstractions.
  • Avoid duplicating knowledge — if something is already expressed in one place (a type, a table, a config value), don't restate it elsewhere in a way that can drift.

Source Control (Git)

Commit

  • Format: type(scope): description
  • Types: feat, fix, refactor, test, docs, chore, ci
  • Scopes: domain, api, web, infra, repo
  • Example: feat(domain): add User aggregate with identity linking

Commit messages are enforced by commitlint.

Development

Tasks are orchestrated with Turborepo. Run from the repo root:

yarn turbo build
yarn turbo dev
yarn turbo lint
yarn turbo test
yarn turbo test:watch
yarn turbo typecheck

Filter to a specific package with -F:

yarn turbo build -F @heim/api
yarn turbo test -F @heim/domain

Infrastructure

yarn turbo dev                                 # Start everything (Postgres + API + Web)
yarn turbo dev -F @heim/api...                 # API + Postgres only
yarn turbo dev -F @heim/web                    # Web only (against remote API)
docker compose -f packages/infra/compose.yml down -v   # Wipe database

Code Style

Class Field Naming

  • Public fields: no prefix (streamId, state)
  • Protected fields: underscore prefix (_state)
  • Private fields: ES private # syntax (#version) — NOT TypeScript private keyword

Testing

  • Mock only the database (SQL) and external APIs. Use real implementations for everything else — crypto, domain logic, helpers, etc. This ensures tests exercise the actual code paths and catch real integration issues. If a component is in-process and has no I/O side effects, wire the real thing.

Project Documentation