# CLAUDE.md — Acme Mid-Market Platform

> Sample CLAUDE.md generated by Blue Sheen for a fictional client (Acme Mid-Market Co., 312-person SaaS for healthcare clinics, HIPAA + SOC 2). The real deliverable from `bluesheen.com/tools/claude-md-generator/` is a markdown file like this one, tuned to your codebase. Drop it at the root of your repo as `CLAUDE.md`; Claude Code auto-discovers and loads it.

## What this is

Acme Mid-Market is a SaaS platform for healthcare clinics in the United States. We help mid-size clinics (10-200 providers) manage scheduling, billing, and clinical workflows. Customers are HIPAA-covered entities, so we are a HIPAA business associate. The platform serves 312 internal users across 27 customers as of 2026-05.

## Stack

- **Backend**: Python 3.12, Django 5.x, Celery for async jobs
- **Frontend**: React 18, TypeScript, Vite, Tailwind
- **Database**: PostgreSQL 15 (managed AWS RDS), Redis for cache/queue
- **Infra**: AWS (us-east-1 + us-west-2 active-passive), Terraform for IaC
- **Data warehouse**: Snowflake (for analytics, NOT for primary operational reads)
- **Observability**: Datadog logs + metrics, Sentry for errors

## Critical business rules — read these first

1. **PHI never appears in logs.** If you add logging, ensure you are not logging request/response bodies that may contain PHI. The `pii_safe_logger` middleware should handle this for HTTP logs but verify for any new logging paths.

2. **All PHI writes audit-trail.** The `AuditLog` model captures who-did-what-when on every PHI field. If you add a new PHI-bearing model, you MUST register it in `acme/audit/registry.py`.

3. **Customers cannot see other customers' data.** Enforced via Django ORM via the `TenantQuerySet` mixin. Every PHI model inherits from `TenantScopedModel`. Never bypass this with `Model.objects.all()` in customer-facing code.

4. **Soft-delete only for PHI.** Records are never hard-deleted via the app. The `soft_delete` decorator is mandatory on any PHI model.

5. **Background jobs run in the customer's tenant context.** Use `with_tenant_context(customer_id)` when scheduling Celery tasks. Forgetting this is a common bug.

## Common gotchas

1. The `users` table is deprecated. Use the `accounts` table. There's a compatibility view but new code must use `accounts`.
2. Datadog is on at write time but data is delayed ~30s. Don't rely on it for verifying a deploy succeeded in real time — use the deploy dashboard.
3. The Celery `default` queue is being deprecated. Use `clinical`, `billing`, `audit`, or `low_priority` queues. Tasks on `default` will be moved manually.
4. `requests.get()` calls to external services should use the `acme.http_client.safe_get()` wrapper, which adds retries and circuit-breaker behavior.
5. Don't write timezone-naive datetimes. The `acme.time.utc_now()` helper enforces UTC + timezone-aware.

## Coding conventions

- **Formatter**: `black` (line length 100) + `isort` for Python, `prettier` for TS/JS. Run via pre-commit hook.
- **Linter**: `ruff` for Python (configured in `pyproject.toml`), ESLint for TS/JS.
- **Type checking**: `mypy --strict` is the goal. Some legacy modules are still `--allow-untyped-defs`; do not add new untyped code.
- **Naming**: `snake_case` for Python, `camelCase` for TS, `PascalCase` for types/components/classes.

## Testing strategy

- **Unit tests**: `pytest` + `pytest-django`. Aim for 80% coverage on new code (enforced in PR check).
- **Integration tests**: `pytest` against a real Postgres test DB (testcontainers). Located in `tests/integration/`.
- **E2E tests**: Playwright, hits a real staging environment. Run nightly + on release branches.
- **TDD**: Encouraged for clinical logic and billing logic. Not strictly required elsewhere.

## Database conventions

- Postgres only. Don't introduce a new database. If you think you need one, talk to the team.
- Migrations: Django migrations. Squash quarterly. Never edit a migration that has shipped to production.
- Indexes: every foreign key gets an index. Composite indexes for any query pattern run > 100 times/day.
- PHI columns: use the `EncryptedTextField` and `EncryptedJSONField` types. Never `TextField` for PHI.

## Authentication & security boundaries

- Customer-facing API: OAuth2 + Bearer tokens, issued via `acme/auth/oauth.py`.
- Internal API (between services): mutual TLS + service tokens.
- Admin / support tools: Okta SSO + role-based access enforced at the view level.
- Never bypass auth in tests. Use the test-user fixtures.
- All PHI endpoints require the `@require_phi_access` decorator AND have rate limits (10/min/user default).

## External integrations

- **Stripe**: billing. Webhook handler at `acme/billing/webhooks.py`. Use idempotency keys.
- **Twilio**: SMS for appointment reminders. Per-customer rate-limited.
- **Salesforce**: CRM sync, nightly via Celery. Two-way sync uses `acme/integrations/salesforce/`.
- **DataMotion**: HIPAA-compliant email. Used for any PHI-bearing outbound email.
- **Snowflake**: analytics warehouse. Pipelines via Airbyte; queries via dbt models in `dbt/`.
- **Datadog + Sentry**: observability. APM enabled in production only.

## Deployment process

- Trunk-based. PRs merge to `main` after review + CI green.
- Auto-deploy to staging on every merge to `main`.
- Manual promote to production via the deploy dashboard. SRE rotation owns the deploy approval.
- Database migrations run automatically as part of deploy. Migrations must be backward-compatible (additive only when running across multiple app versions).

## Common patterns

- **Adding a new PHI model**: inherit from `TenantScopedModel`, register in `acme/audit/registry.py`, use `EncryptedTextField` for PHI columns, add audit hook in `signals.py`, write migration.
- **Adding a new Celery task**: pick the correct queue (`clinical`/`billing`/`audit`/`low_priority`), wrap with `with_tenant_context`, write unit test that calls the task synchronously, write integration test for end-to-end behavior.
- **Adding a new feature flag**: use the `acme.flags` module (LaunchDarkly-backed). Document the flag in `docs/feature-flags.md`. Set a removal-by date.
- **Hot-fixing production**: branch from the production tag, fix, test in staging, deploy. Backport to `main` after.

## Development workflow

```bash
# First-time setup
git clone git@github.com:acme/platform.git && cd platform
make bootstrap   # installs deps, sets up local Postgres + Redis via docker-compose, runs migrations, seeds dev data

# Daily
make dev         # starts the dev server + worker + flower (Celery monitor)
make test        # runs unit tests
make test-integration  # runs integration tests (slower)
make lint        # ruff + mypy + eslint + prettier check
make format      # auto-fix lint issues where possible
```

## Files to read first

For new engineers (and for Claude when you're new to a task):

- `docs/architecture.md` — high-level system diagram
- `acme/auth/oauth.py` — how authentication works
- `acme/audit/registry.py` — PHI model registration
- `docs/feature-flags.md` — what's behind a flag and why
- `docs/incident-runbook.md` — what to do when production is on fire

## Anti-patterns — do NOT do these

- Calling `Model.objects.all()` in customer-facing code without a tenant filter. This is a PHI breach in waiting.
- Adding `requests.get()` directly instead of using `safe_get()`. Bypasses retries and circuit breakers.
- Catching `Exception` broadly without logging. We've lost incidents to silent failures.
- Migrations that aren't backward-compatible. They break deploys.
- New code on the `default` Celery queue.
- Logging request bodies on PHI endpoints. The `pii_safe_logger` should prevent this but verify.
- Hard-coding customer IDs anywhere. Use environment configuration or test fixtures.

## Things this doc deliberately doesn't cover

- Frontend conventions (separate `client/CLAUDE.md` in the React app)
- dbt model conventions (separate `dbt/CLAUDE.md`)
- Terraform conventions (separate `infra/CLAUDE.md`)
- Customer-facing API spec (autogenerated OpenAPI; see `docs/api/`)
- Onboarding for non-engineering roles (Notion has separate docs)

---

*Sample generated by Blue Sheen at bluesheen.com/tools/claude-md-generator/. Your real CLAUDE.md will be tailored to your codebase, business rules, and team. Free, 2 business days.*