miclaw-app 0.1.0

package/.next/standalone/.next/server/app/rules.segments/rules/__PAGE__.segment.rsc

@@ -0,0 +1,2344 @@
+1:"$Sreact.fragment"
+2:I[22450,["/_next/static/chunks/0mmpyn9fv2fjf.js","/_next/static/chunks/0d3shmwh5_nmn.js","/_next/static/chunks/12p3iqtw2ohfq.js"],"ExpandableBody"]
+16:I[97367,["/_next/static/chunks/0mmpyn9fv2fjf.js","/_next/static/chunks/0d3shmwh5_nmn.js"],"OutletBoundary"]
+17:"$Sreact.suspense"
+3:T133b,# RULES
+
+- Always use concise explanation
+- Main languages are Python and TypeScript
+- Never use emojis when writing code or markdown
+- NEVER use non-standard symbols like "✓|✗|☐|○" when writing code or markdown
+- Use parametrized tests whenever possible
+- Listed below are a handful of different 'Workflow' guides. Adhere to them as best as possible
+- Whenver novel work (not in a repo) is being done in python, ALWAYS use a .venv prior to installing any packages via pip or otherwise.
+
+## REPOS
+
+Before working in any repo, read its instruction file:
+
+| Repo | Path | Instructions |
+|------|------|--------------|
+| platform-services | ~/Desktop/platform-services | AGENTS.md |
+| infrastructure | ~/Desktop/infrastructure | CLAUDE.md |
+| web-app | ~/Desktop/web-app | .clauderules |
+
+When spawning subagents for a specific repo, include the instruction file path in the prompt.
+
+## Code Quality Standards
+
+Code must be clean, readable, and maintainable. Hold yourself to extremely high standards:
+
+- **Small, focused functions**: Break complex logic into small, single-purpose functions. If a function has more than 2-3 levels of nesting or more than 6 return statements, decompose it.
+- **Typed end-to-end**: Use Pydantic models and dataclasses instead of raw `dict[str, Any]`. When parsing external data (JSON, API responses), validate into typed models at the boundary and work with typed objects throughout.
+- **Minimal suppression comments**: `# noqa`, `# pyright: ignore`, `# pragma: no cover`, and `# type: ignore` should be rare exceptions, not workarounds for poor typing. If you find yourself adding a suppression, first try to fix the underlying type issue. Acceptable uses: subprocess security warnings on known binaries, `__main__` guards, shared type-only files.
+- **No `dict[str, Any]` in business logic**: Parse into typed models at the boundary. If a function accepts `dict[str, Any]`, it should be a private parsing helper, not business logic.
+- **Parametrized tests**: Combine similar test cases with different inputs into `@pytest.mark.parametrize` instead of copy-pasting test methods.
+- **Extract repeated patterns**: If the same mock setup or helper logic appears 3+ times, extract it to a fixture or helper function.
+
+## Git Restrictions
+
+Agents must NEVER run `git add` or `git commit` commands. The user will handle all git staging and commits manually.
+
+## PR Review Workflow (ps-copy)
+
+There is a second copy of platform-services at `~/Desktop/ps-copy/platform-services` used for reviewing PRs.
+
+When asked to "Review PR <number> in ps-copy":
+1. Navigate to `~/Desktop/ps-copy/platform-services`
+2. Checkout main branch: `git checkout main`
+3. Run `git fetch && git pull`
+4. Read in the repositories developmnet guide AGENTS.md file (FAIL IF YOU CANNOT FIND IT)
+5. Run the `/review` task for the specified PR
+6. DO NOT post an actual comment on the review. Just review locally.
+
+## Linear Ticket Workflow
+
+- Ticket titles must be under 50 characters. Linear auto-generates branch names from titles, so short titles produce clean branch names.
+- Tickets are NOT done until the code has been reviewed and merged in GitHub. Do not mark Linear tickets as "Done" just because the code is written - they must go through the full PR review process first.
+
+## Cross-Repo Workflow
+
+When working across multiple repos in a single task:
+1. Read all relevant instruction files first
+2. Follow each repo's conventions when modifying its code
+3. Coordinate changes that span repos (e.g., API changes in platform-services affecting web-app)
+
+## Querying Logs in Axiom Workflow
+
+Querying Logs in Axiom
+
+Logs are in the `bioscope-dev` dataset for the dev AWS environment and the `bioscope-prod` dataset for the prod AWS environment. Axiom uses APL (similar to Kusto/KQL). All field names are **camelCase**.
+
+### Key Fields
+
+| Field | Description |
+| ------- | ------------- |
+| `_time` | Timestamp |
+| `logGroup` | CloudWatch log group (e.g., `/aws/lambda/account-service`) |
+| `message` | Log message |
+| `levelname` | Log level (`INFO`, `ERROR`, etc.) |
+| `service` | Service name |
+| `correlationId` | UUID for tracing requests across services |
+| `accountId`, `userId`, `patientId` | Entity identifiers |
+| `path`, `method`, `statusCode`, `took` | HTTP request details |
+| `errorMessage`, `errorType` | Error details |
+| `data` | Object containing extra fields not in the standard set |
+
+### Example Queries
+
+```apl
+// Errors in a service
+['bioscope-dev']
+| where levelname == "ERROR" and logGroup == "/aws/lambda/account-service"
+
+// Trace a request across services
+['bioscope-dev']
+| where correlationId == "550e8400-e29b-41d4-a716-446655440000"
+| order by _time asc
+
+// Slow requests
+['bioscope-dev']
+| where took > 1000
+| project _time, service, path, took
+
+// Error counts by service (last hour)
+['bioscope-dev']
+| where _time > ago(1h) and levelname == "ERROR"
+| summarize count() by logGroup0:{"rsc":["$","$1","c",{"children":[["$","div",null,{"className":"mx-auto max-w-5xl px-8 py-10","children":[["$","div",null,{"className":"mb-8","children":[["$","div",null,{"className":"flex items-baseline gap-3","children":[["$","h1",null,{"className":"text-2xl font-medium tracking-tight","children":"Rules and Instructions"}],["$","span",null,{"className":"text-sm text-text-muted","children":12}]]}],["$","p",null,{"className":"mt-1 text-sm text-text-muted","children":"Repo instruction files that guide agent behavior"}]]}],[["$","div","Desktop",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"Desktop"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/CLAUDE.md"}]]}],["$","$L2",null,{"content":"$3","previewLines":8}]]}]]}]]}],"$L4","$L5","$L6","$L7","$L8"],false]}],["$L9"],"$La"]}],"isPartial":false,"staleTime":300,"varyParams":null,"buildId":"BgLP6ChyOyE0k8Ahr8F2H"}
+b:Tcb1,# Bioscope Bioinformatics 2026 Roadmap
+
+## Project Overview
+Interactive roadmap visualization tool for Bioscope Bioinformatics' 2026 strategic planning. Single-page web app with a Node.js backend for data persistence.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `roadmap.html` | Main application - all HTML, CSS, and JavaScript in one file |
+| `roadmap-data.json` | Data storage - umbrellas, projects, subtasks, timelines |
+| `server.js` | Node.js server (port 3000) - serves HTML and handles JSON read/write |
+
+## How to Run
+```bash
+cd /Users/gabry/Desktop/ROADMAP_2026
+node server.js
+# Open http://localhost:3000
+```
+
+## Data Model
+
+```json
+{
+  "umbrellas": [
+    {
+      "id": "wgs",
+      "title": "WGS (Whole Genome Sequencing)",
+      "icon": "🧬",
+      "projects": [
+        {
+          "id": 1,
+          "title": "Project Name",
+          "monthStart": 0,      // 0-11 (Jan-Dec), null = TBD
+          "monthEnd": 2,        // 0-11 (Jan-Dec), null = TBD
+          "subtasks": [
+            { "id": 101, "text": "Task description", "note": "Optional note" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Umbrella Categories
+- `wgs` - WGS (Whole Genome Sequencing) 🧬
+- `microbiome` - Microbiome 🦠
+- `omics` - Other Omics & Tooling 🔬
+
+## Key Features Implemented
+
+### Two Views
+1. **Projects View** - Expandable umbrella tiles with two-column layout (projects list | tasks panel)
+2. **Timeline View** - Gantt-style visualization across 12 months with Q1-Q4 labels
+
+### Timeline Interactions
+- **Drag rows** to reorder projects within an umbrella
+- **Drag rows between umbrellas** to move projects to different categories
+- **Drag timeline bars** left/right to move project timing
+- **Drag bar edges** (resize handles) to expand/shrink duration
+- **Tooltip** shows month range while dragging (e.g., "April - September")
+- **TBD projects** shown as dashed badge - click to set timeline
+
+### Edit Functionality
+- Edit button on each project (both views)
+- Modal with title and month range (January-December dropdowns)
+- Delete project option
+
+### Data Persistence
+- **Save button** - POST to `/api/data` writes to `roadmap-data.json`
+- **Export button** - Downloads JSON file
+- LocalStorage used for UI state (expanded umbrellas, selected projects)
+
+## Technical Notes
+
+### Month-Based Timeline
+Changed from quarter-based (Q1-Q4) to month-based (0-11) for finer control:
+- `monthStart: 0` = January
+- `monthEnd: 11` = December
+- `null` values = TBD (unscheduled)
+
+### CSS Variables (theming)
+```css
+--wgs-color: #3b82f6      /* Blue */
+--microbiome-color: #10b981  /* Green */
+--omics-color: #8b5cf6    /* Purple */
+```
+
+### Key JavaScript Functions
+- `renderProjectsView()` - Renders umbrella tiles
+- `renderTimeline()` - Renders Gantt chart
+- `initTimelineDragDrop()` - Row drag/drop between umbrellas
+- `initBarDragResize()` - Timeline bar drag/resize
+- `saveToServer()` - POST data to server
+- `loadFromServer()` - GET data from server
+
+## Potential Future Enhancements
+- Progress tracking (checkboxes were removed but could be re-added)
+- Dependencies between projects (arrows/lines)
+- Multiple years view
+- Team/owner assignment
+- Color customization per project
+- Export to PDF/image
+- Milestones/markers on timeline4:["$","div","ROADMAP_2026",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"ROADMAP_2026"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/ROADMAP_2026/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/ROADMAP_2026/CLAUDE.md"}]]}],["$","$L2",null,{"content":"$b","previewLines":8}]]}]]}]]}]
+c:Tfec,# Repository Standards
+
+## CRITICAL SAFETY RULES
+
+**NEVER RUN APPLIES**
+Claude can ONLY run the following commands. All apply operations must be performed by humans.
+
+```bash
+# Allowed
+tofu validate
+tofu fmt
+tofu fmt -check -diff -recursive
+tofu init
+
+# NEVER run
+tofu apply
+tofu destroy
+```
+
+For the commands that are allowed, you can and should `cd` into the appropriate stack or module directory and run the command.
+
+## Repository Structure
+
+- `stacks/` - Environment-specific configurations with separate state management
+- `modules/` - Reusable OpenTofu modules (some modules may also call other modules)
+
+## Code Standards
+
+### Main Files
+
+All resources must be in modules, never in a main.tf under the `stacks/` directory. The main.tf should only call other modules.
+
+### Module Standards
+
+- Each resource type goes in an appropriately named *.tf file (IAM resources in iam.tf, etc.)
+- Include variables.tf and outputs.tf with descriptive descriptions. These files are only necessary when the module actually accepts variables or exposes outputs -- do not create empty or placeholder files. Only define outputs that have a downstream consumer; do not add outputs preemptively.
+- Every module must include a README.md that provides an overview of what the module provisions and any gotchas
+- Do NOT include usage examples in README--module usage should be self-documenting; instead include an overview of the module's purpose and any gotchas with it
+
+### General Conventions
+
+- Use consistent naming: `{service_name}_{resource_type}`
+- Never hardcode secrets or credentials
+
+## Web Search
+
+Since much of this repo has to do with AWS and GCP resources, you can and should use web search to find documentation on the resources you are working with. When something is unclear, always prefer using web search to using your internal knowledge.
+
+## GitHub Actions
+
+All external GitHub Actions in workflow files must be pinned to commit SHAs, not version tags. Version tags are mutable and can be hijacked in a supply chain attack. Add the version as a comment for readability.
+
+```yaml
+# Good
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+# Bad
+- uses: actions/checkout@v4
+```
+
+Internal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.
+
+## Pull Request Guidelines
+
+### Cross-Repo Dependency Ordering
+
+`infrastructure` (this repo) is the IaC repo, while `platform-services` contains the Python application code. `infrastructure` changes can break `platform-services` if applied out of order. Review PRs with these checks:
+
+- If a code change in this repo provisions a **new Lambda**, that lambda's code must be set up in `platform-services` and promoted to prod *before* the infrastructure PR is merged. This is because `platform-services` deploys the lambda's code as a zip file and uploads it to S3. If that S3 file does not exist when `infrastructure` tries to deploy the lambda, the deployment will fail. Even a simple skeleton lambda handler is sufficient. If you see a new lambda being provisioned in this repo, leave a comment asking the author to confirm that the corresponding `platform-services` PR that sets up the lambda is already merged and promoted to prod.
+- We use a direct invocation pattern for lambdas called "operations"; lambdas implement operations as a routing mechanism for which internal logic to execute. If you see a new operation name in an infrastructure code change, such as in an EventBridge schedule or step function step, that operation must be set up in `platform-services` and promoted to prod *before* the infrastructure PR is merged. If you see a new operation being provisioned in this repo, leave a comment asking the author to confirm that the corresponding `platform-services` PR that sets up the operation is already merged and promoted to prod.
+
+### Code Standards in Reviews
+
+When reviewing code, ensure it adheres to the code standards guidelines outlined in the [README](./README.md). It is ok to leave small, low-priority comments about code standards violations.5:["$","div","infrastructure",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"infrastructure"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/infrastructure/AGENTS.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"AGENTS.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/infrastructure/AGENTS.md"}]]}],["$","$L2",null,{"content":"$c","previewLines":8}]]}],"$Ld"]}]]}]
+e:T838e,# Platform Services Development Guide
+
+This is a Python monorepo using Nx and uv for managing dependencies and builds. Testing is done with pytest. Most packages are either deployed as AWS Lambda functions or shared libraries.
+
+## Project Structure
+
+This is a monorepo containing multiple Python packages that follow consistent patterns and conventions.
+
+## Account Types
+
+There are two account types, stored as `account_type` in the `accounts` DynamoDB table:
+
+- **`self-evaluation`** (aka "Try it on Yourself") — An individual signs up to evaluate Bioscope on themselves. They act as both the physician and the patient. One user, one patient, one-time payment. Paid if there's an active `selfEvaluationAccess` entitlement in the `account-entitlements` DynamoDB table.
+- **`practice`** — A practice with one or more physicians and potentially many patients. Has two billing models:
+  - **Enterprise** — created by a Bioscope employee, all billing is manual/out-of-band, all patients always considered paid. Identified by an `enterpriseProvisionedAccount` entitlement in the `account-entitlements` DynamoDB table.
+  - **Standard** — physician self-signs up, billing is per-patient via yearly subscriptions tracked in the `patient-entitlements` table.
+
+For full details, see the [Account Types and Billing Statuses](https://www.notion.so/Account-Types-and-Billing-Statuses-32713dc5995980a89921f096af7b57a5) Notion page (if you have access to Notion MCP).
+
+## GitHub Actions
+
+All external GitHub Actions in workflow files must be pinned to commit SHAs, not version tags. Version tags are mutable and can be hijacked in a supply chain attack. Add the version as a comment for readability.
+
+```yaml
+# Good
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+# Bad
+- uses: actions/checkout@v4
+```
+
+Internal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.
+
+## Dockerfile Dependency Installation
+
+All Dockerfiles must use lockfile-deterministic dependency installs. Never use `uv pip install -e` or `pip install -e` directly, as these resolve against PyPI at build time and ignore the lockfile.
+
+### Standard pattern (uv-based images)
+
+For Dockerfiles that use uv and target the project's Python version:
+
+```dockerfile
+# Export lockfile-pinned dependencies and install without resolution
+RUN uv export --frozen --no-dev --no-editable --package <package-name> -o /tmp/requirements.txt && \
+    uv pip install --system --no-deps -r /tmp/requirements.txt
+```
+
+This mirrors the Lambda bundler pattern (`bundle_lambda.py` / `bundle_layer.py`). The `--frozen` flag ensures exact versions from `uv.lock` are used, and `--no-deps` prevents any resolution against PyPI.
+
+### Non-uv base images (e.g., mriqc, fastsurfer)
+
+For Dockerfiles that extend specialized base images with a different Python version, install uv into the base image and use `uv sync` to create a venv with the project's Python version. The app runs on that version while the base image's tools stay on their own Python:
+
+```dockerfile
+FROM <base-image>
+USER root
+WORKDIR /app
+
+RUN pip install --no-cache-dir "uv>=0.10.0,<0.11.0"
+
+COPY pyproject.toml uv.lock ./
+COPY packages/<workspace-deps>/ ./packages/<workspace-deps>/
+
+# Install Python under /app so non-root users can access it
+ARG PYTHON_VERSION
+ENV UV_PYTHON_INSTALL_DIR=/app/.python
+RUN uv sync --frozen --no-dev --python ${PYTHON_VERSION} --package <package-name>
+
+ENTRYPOINT ["/app/.venv/bin/python", "-m", "<package_module>.main"]
+```
+
+### Non-workspace dependencies
+
+Any `pip install` of packages not managed by the workspace lockfile (e.g., `awscli` in utility images) must use an exact version pin (`==`). Unconstrained `pip install <package>` is not allowed.
+
+## Pull Request Guidelines
+
+### Cross-Repo Dependency Ordering
+
+`platform-services` (this repo) contains Python application code, while `infrastructure` provisions the AWS resources that the application code runs on. `platform-services` often depends on `infrastructure` changes. To avoid mistimed prod promotions breaking due to ordering, review PRs based on the following:
+
+If a code change in this repo introduces the **first usage** of an infrastructure-managed resource (DynamoDB table/index, S3 bucket, SQS queue, SNS topic, Secrets Manager secret, etc.), leave a comment asking the author to confirm that the corresponding `infrastructure` PR that provisions the resource is already merged and promoted to prod or to confirm that this is purely greenfield development that is not yet exposed to customers in the product.
+
+### Dependency Pinning
+
+All external package dependencies must use the compatible release operator (`~=`). Do not use `>=` as it leaves the version unbounded. Exact pins (`==`) are acceptable when a package requires a specific version.
+
+### Code Standards
+
+When reviewing code, ensure it adheres to the code standards guidelines outlined in the [README](./README.md), specifically with regard to mocking, Pydantic models, AWS service interaction, middleware usage, etc. It is ok to leave small, low-priority comments about code standards violations.
+
+It is also ABSOLUTELY CRITICAL to ensure that log statements do not contain PII/PHI data. Instead, use internal UUIDs to identify users, accounts, patients, resources, etc. See the [PII/PHI Logging Rules](#piiphi-logging-rules) section for the complete list of prohibited and safe fields.
+
+For logging, error handling, traceability, etc. it's also critical that any new lambda handler uses the standard `lambda-handler` package and the `BioscopeLogger` and that any new rest API lambda uses the standard `shared-middleware` package.
+
+### IDOR Prevention
+
+When reviewing route handlers, watch for authorization gaps that could allow users to access or modify resources belonging to other accounts/patients:
+
+- **Patient routes**: Any route with `{patient_id}` in the path must use `Depends(validate_patient_account_from_path_as_patient)` (from `shared_middleware`). This middleware calls account-service to verify the patient belongs to the requesting account. If a route takes a patient ID without this dependency and does not do patient validation internally, it's an IDOR vulnerability.
+- **Always use the validated patient result**: When a route uses `validate_patient_account_from_path_as_patient`, always name the dependency `patient` (never `_`). If the route also takes a sub-resource ID (e.g., `{chat_id}`, `{file_id}`), the service layer must verify that the fetched resource's `patient_id` matches `patient.patient_id`. Discarding the patient dependency with `_` is a red flag — it means the patient-to-resource ownership check is likely missing.
+- **Other resource routes**: Routes that fetch a resource by ID (e.g., orders, EHR connections) must verify `resource.account_id == account_id` before returning or mutating it. If the resource is patient-specific (contains a `patient_id` field), the route must also validate that `resource.patient_id == patient_id`.
+- **List/query endpoints**: Queries that return collections must scope by `account_id` (or `patient_id` where applicable) to prevent cross-account data leakage.
+- **Trusted headers**: The `Bioscope-Account-Id` and `Bioscope-User-Id` headers are validated by the API Gateway account authorizer and can be trusted for authorization checks. Use these (via `BioscopeAccountIdHeaderDeps`, `BioscopeUserIdHeaderDeps`), and NEVER trust account id or user id from path params, query params, or request bodies.
+
+### Billing Enforcement
+
+Any route that creates or modifies patient data or consumes metered resources (e.g., LLM tokens, test orders) must enforce billing via the billing validation middleware from `shared_middleware.billing_validation`:
+
+- **`ensure_patient_billing_access_from_path`**: Use when `patient_id` is a path parameter. Add as a `Depends()` dependency on the route.
+- **`ensure_patient_billing_access_from_body`**: Use when `patient_id` is in the request body (as `patientId` at the root level). Add as a `Depends()` dependency on the route.
+
+Both middlewares invoke account-service to check the account's billing entitlements and return a 403 with a specific denial reason if access is not granted. Read-only routes (listing, viewing) do not require billing enforcement.
+
+## Commands
+
+Nx commands are run with:
+
+```bash
+pnpm exec nx run <package-name>:<command>
+```
+
+For example, to run tests for the `dynamodb-helper` package:
+
+```bash
+pnpm exec nx run dynamodb-helper:test
+```
+
+Available commands are defined in `nx.json` at the root and in each package's `project.json` file.
+
+### Formatting, Linting, and Type Checking
+
+For code quality, ALWAYS run formatting, linting, and type checking after making changes. These are three separate commands — `format` and `lint` are NOT the same thing, even though both use `ruff` under the hood. `format` fixes code style (whitespace, line length, etc.) while `lint` catches code quality issues (unused imports, bad practices, etc.). ALWAYS run all three of the following commands after making changes:
+
+```bash
+pnpm exec nx run <package-name>:format
+pnpm exec nx run <package-name>:lint
+pnpm exec nx run <package-name>:type-check
+```
+
+**IMPORTANT**: You MUST run `format`, `lint`, and `type-check` commands (in addition to tests) after making changes to ensure your code is correct. Fix all formatting, linting, and type checking issues before considering the task complete.
+
+## Types
+
+This repo makes heavy use of Pydantic V2 models. Shared models are typically defined in the `bioscope-types` package.
+
+We have a `BioscopeBaseModel` class that is a subclass of `BaseModel` that adds some additional functionality, mostly adding camelCase aliases to the fields.
+In our code, we use snake_case for everything, but anything leaving or entering Python should be camelCase, for example:
+
+- Network requests and responses
+- Database rows
+- Logging statements
+
+The shared `BioscopeBaseModel` automatically takes care of this for us.
+
+## FastAPI Routes (`packages/**/src/**/routes/**.py`)
+
+### Basic Conventions
+
+- Route functions should be async
+- Router should have a common prefix per file
+- Follow standard REST conventions
+
+### Headers and Authentication
+
+These routes are configured with an AWS API Gateway. Most routes are secured with a custom lambda authorizer.
+
+This authorizer validates the Bearer JWT token and extracts the user ID from the token.
+Requests come in with a `Bioscope-Account-Id` header that contains the account ID.
+The authorizer ensures that the user in the JWT belongs to the account.
+This means that these headers are "safe" and guaranteed to be valid for the calling user.
+
+Therefore, authorization (i.e. to prevent IDOR, etc.) should be done via these headers.
+
+These headers can be injected into the route function as dependencies using the `BioscopeUserIdHeaderDeps` and `BioscopeAccountIdHeaderDeps` classes.
+
+### Models
+
+Request and response models should both be Pydantic models that inherit `BioscopeBaseModel`.
+`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.
+
+### Logging
+
+Routes should use the `BioscopeLoggerDeps` class to inject the logger into the route function.
+This logger is automatically configured to include the user ID and account ID in the log messages.
+
+#### PII/PHI Logging Rules
+
+**Fields that must NEVER be logged:**
+
+- Patient names, emails, phone numbers, addresses, dates of birth
+- Medical data (diagnoses, medications, lab results, clinical notes)
+- Full request/response bodies from external APIs (FHIR, EHR, lab vendors, etc.)
+- Webhook payloads (these often contain patient data or credentials)
+- Secrets, tokens, API keys, credentials — omit these entirely (no length hints either)
+- Template parameters that contain patient-facing content (e.g., SMS/email body text)
+
+**Safe fields that CAN be logged:**
+
+- Internal UUIDs: `patient_id`, `account_id`, `user_id`, `order_id`, `connection_id`, `correlation_id`
+- Status codes, HTTP methods, URL paths
+- Counts and lengths (e.g., number of records processed, response body length)
+- Template/event names, enum values, operation names
+- Durations, timestamps, retry counts
+
+**Redaction pattern** — when context about a sensitive value is needed for debugging, log a length hint instead of the value:
+
+```python
+# Good — log a length hint for debugging without exposing the value
+logger.info("received webhook", extra={"bodyLength": len(body)})
+
+# Good — log only safe identifiers
+logger.info("processing patient", extra={"patientId": patient_id, "accountId": account_id})
+
+# Bad — logs the entire webhook/response body (may contain PII/PHI)
+logger.info("received webhook", extra={"body": body})
+logger.info("API response", extra={"response": response.json()})
+```
+
+**Never log full request/response bodies** — log the status code and body length instead:
+
+```python
+# Good
+logger.info("FHIR response", extra={"statusCode": response.status_code, "bodyLength": len(response.content)})
+
+# Bad
+logger.info("FHIR response", extra={"body": response.json()})
+```
+
+**Exception messages** — do not embed API response text in exception messages, as these end up in logs via `logger.exception`:
+
+```python
+# Good
+raise ValueError(f"EHR API returned {response.status_code}")
+
+# Bad — response body may contain PHI
+raise ValueError(f"EHR API error: {response.text}")
+```
+
+#### Formatting
+
+Do not wrap values in `str()` when passing them as log `extra` fields. `BioscopeLogger` handles serialization automatically. For example, use `extra={"patientId": patient_id}`, not `extra={"patientId": str(patient_id)}`. With this in mind, you also do not need to JSON-stringify any logged models; you can pass in a Python dict to `extra` (though be careful that any logged models do not contain PII or PHI, per the rules above).
+
+```python
+# Good
+extra={"metric": usage_metric.model_dump()}
+
+# Bad
+extra={"metric": usage_metric.model_dump_json()}
+extra={"metric": json.dumps(usage_metric.model_dump())}
+```
+
+### HTTP Client
+
+`httpx` is our preferred HTTP client. Do not use `requests` or `aiohttp` for new code. If another external library requires `aiohttp` or `requests`, that is fine. An example of this is `slack-sdk` which requires `aiohttp`.
+
+When testing code that uses `httpx`, use `respx` for mocking. Use the **pytest fixture pattern for this**.
+
+### Relative Versus Absolute Imports
+
+Production code should always use absolute imports. For example:
+
+```python
+from account_service.models import Account  # GOOD
+from .models import Account  # BAD
+```
+
+However, test directories are not modules. They cannot and should not contain `__init__.py` files. Therefore, relative imports must be used in test directories. For example:
+
+```python
+from .conftest import build_data  # GOOD
+from tests.conftest import build_data  # BAD
+```
+
+### Error Handling
+
+Raise `HTTPException` with appropriate status code and detail message
+
+## Lambda Handlers (`packages/**/handler.py`)
+
+### Handler Types
+
+1. **LambdaHandler** - base handler for non-API Gateway functions
+2. **HttpHandler** - extends LambdaHandler with API Gateway support (requires `lambda-handler[api]`)
+
+### Lazy Loading Pattern
+
+Many lambdas serve both as direct invocation functions and API Gateway integrations. Loading Python modules can be slow (100s of milliseconds), especially with many Pydantic models. This impacts cold start time.
+
+**Solution**: Use lazy loading in `handler.py` files only. Load direct invocation handling code only when needed, and vice versa for API Gateway routes.
+
+**Example**:
+
+```python
+from lambda_handler.http_handler import HttpHandler
+
+def get_app():
+    from my_service.app import app  # noqa: PLC0415
+    return app
+
+handler = HttpHandler(get_app)
+
+@handler.direct_invocation()
+def handle_direct_invocation(event: DirectInvocationEvent, logger: BioscopeLogger):
+    from my_service.handlers.handler_one import handle_handler_one  # noqa: PLC0415
+    return handle_handler_one(event, logger)
+```
+
+**Important**:
+
+- Restrict lazy imports to `handler.py` only
+- Keep common imports (logger, types, handler framework) at module level
+- Use `# noqa: PLC0415` to suppress linting warnings
+- Never lazy load in business logic or service modules
+
+### Decorators
+
+| Event Source      | Decorator                    | Required kwarg         | Notes                                    |
+| ----------------- | ---------------------------- | ---------------------- | ---------------------------------------- |
+| SQS               | `@handler.sqs`               | `queue_name="<queue>"` |                                          |
+| SNS               | `@handler.sns`               | `topic_name="<topic>"` |                                          |
+| Direct Invocation | `@handler.direct_invocation` | N/A                    | Operation extracted from request model   |
+| Event Bridge      | `@handler.event_bridge`      | N/A                    | Handles all EventBridge events           |
+| API Gateway Auth  | `@handler.authorizer`        | N/A                    | For custom API Gateway authorizers       |
+| Health Check      | `@handler.health_check`      | N/A                    | Custom health check (built-in available) |
+
+**Notes**:
+
+- EventBridge and authorizer handlers do not use operation discriminators - they handle all events of their type sent to the function.
+- Direct invocation handlers automatically extract the `operation` from the request model's `operation` class attribute.
+- A built-in health check handler is automatically registered for all Lambda functions and responds to `{"operation": "healthCheck"}` requests.
+
+### Message Payloads
+
+• Define a Pydantic model that **inherits `BioscopeBaseModel`** for every distinct message body.
+• Models should be defined in the `bioscope_types` package under the `services` module.
+
+Always annotate the first parameter with the corresponding event model from `lambda_handler.models`, e.g. `SqsEvent[MyMessage]`.
+`MyMessage` should be a new Pydantic model that inherits `BioscopeBaseModel`.
+`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.
+
+### Dependency Injection
+
+Handler functions may declare these optional parameters which will be injected automatically:
+
+- `logger: BioscopeLogger` - the project-wide structured logger.
+- `context: LambdaContext` - the AWS Lambda context object.
+
+### Example (SQS)
+
+```python
+from lambda_handler.handler import LambdaHandler
+from lambda_handler.models.sqs import SqsEvent
+from bioscope_types.common import BioscopeBaseModel
+
+handler = LambdaHandler()
+
+class MySqsMessage(BioscopeBaseModel):
+    my_custom_field: str
+
+@handler.sqs(queue_name="my-queue")
+def handle_sqs_event(event: SqsEvent[MySqsMessage], logger, context):
+    logger.info("processing message", extra={"myCustomField": event.body.my_custom_field})
+```
+
+### Style Rules
+
+- Use **explicit type annotations** everywhere.
+- Keep handler bodies minimal; delegate business logic to service modules.
+- Use the provided `logger`, not `print`, for output.
+- Do not log PII/PHI data. Follow the [PII/PHI Logging Rules](#piiphi-logging-rules) in the FastAPI Routes section — the same rules apply to Lambda handlers. Never log full event bodies, external API responses, webhook payloads, tokens, API keys, credentials, or other secrets.
+
+### Handler Organization (`packages/**/src/**/handlers/**/*.py`)
+
+For services with many direct invocation handlers, organize them in a dedicated `handlers` directory rather than implementing the business logic directly in `handler.py`.
+
+### Structure
+
+```text
+src/
+  service_name/
+    handler.py          # Contains @handler.direct_invocation decorators
+    handlers/
+      __init__.py       # Exports all handler functions
+      handler_one.py    # Individual handler implementation
+      handler_two.py    # Individual handler implementation
+```
+
+### Handler Function Signature
+
+Handler functions should follow this standardized signature:
+
+```python
+async def handle_operation_name(
+    args: OperationArgs,
+    logger: BioscopeLogger,
+) -> OperationResponse:
+    # Implementation here
+```
+
+Where:
+
+- `args` is the operation's arguments model from `bioscope_types.services`
+- `logger` is the structured logger instance
+- Return type matches the operation's response model
+
+### Main Handler File
+
+The main `handler.py` file should delegate to the individual handlers:
+
+```python
+from service_name.handlers import handle_operation_name
+
+@handler.direct_invocation()
+async def operation_name_handler(
+    event: OperationRequest, parent_logger: BioscopeLogger
+) -> OperationResponse:
+    return await handle_operation_name(
+        args=event.args,
+        logger=parent_logger.child(
+            {
+                # Add relevant fields from event.args (in camelCase and avoiding PHI/PII)
+            }
+        ),
+    )
+```
+
+## AWS Services (`packages/**/src/**/aws.py`)
+
+**All** AWS service clients should be abstracted using context managers in a dedicated `aws.py` file. This pattern should be used for all AWS services **except** those with specialized helper packages (i.e. S3 via `s3_helper`, SQS via `queue_helper`, and DynamoDB via `dynamodb_helper`).
+
+### AWS Abstraction Pattern
+
+Create `src/package_name/aws.py`:
+
+```python
+from contextlib import asynccontextmanager
+from aioboto3 import Session
+
+session = Session()
+
+@asynccontextmanager
+async def get_service_name():
+    async with session.client("service-name") as client:
+        yield client
+```
+
+### Usage in Production Code
+
+```python
+from package_name.aws import get_service_name
+
+async def some_operation() -> None:
+    async with get_service_name() as client:
+        await client.some_api_call()
+```
+
+## Testing (`packages/**/tests/**/*.py`)
+
+### Basic Rules
+
+- Prefer **pytest** for all unit tests.
+- Use **botocore.stub.Stubber** for mocking AWS services (don't use `mock.patch` directly on the service) except in the `dynamodb_helper` package which uses `moto` for mocking.
+- Tests are all run with `asyncio_mode = "auto"` in `pyproject.toml`, so tests don't need to be marked as async individually.
+- **AVOID** asserting on logger calls except in very limited cases. Use a real BioscopeLogger instance (see Logger Fixture section) rather than mocking it. If you absolutely need to test logging behavior, use `caplog: pytest.LogCaptureFixture`. (see @bioscope_logger/README.md)
+- Use pytest fixtures for both mocking and for defining common test data.
+- Test all cases for 100% test coverage, but don't overdo it with tests. And don't waste time testing code that is not written by us; i.e. don't write a test that effectively tests a library.
+- Under **no circumstances** should you write large amounts of code in a test file and then write tests that effectively test that code instead of the code in the actual production file.
+
+### Test Structure
+
+- Mirror source code structure in test organization
+- Individual classes for each function being tested
+- Individual methods for each test case
+
+Example:
+
+```python
+class TestCopyS3ToTemp:
+    def test_happy_path(self):
+        pass
+
+    def test_invalid_url_format(self):
+        pass
+
+    def test_s3_error(self):
+        pass
+```
+
+### Assertions
+
+When performing assertions on data, compare the entire object as much as possible rather than individual assertions for each field.
+
+For example, instead of:
+
+```python
+assert result is not None
+assert len(result) == 1
+assert result[0].id == "123"
+assert result[0].name == "John Doe"
+assert result[0].email == "john.doe@example.com"
+```
+
+you should do:
+
+```python
+assert result == [User(
+    id="123",
+    name="John Doe",
+    email="john.doe@example.com"
+)]
+```
+
+When performing assertions on what functions were called with, use the built in assert calls like `assert_called_once_with` rather than checking the arguments directly.
+For example, instead of:
+
+```python
+assert mock_foo.call_args.args == ("123", "John Doe", "john.doe@example.com")
+```
+
+you should do:
+
+```python
+mock_foo.assert_called_once_with("123", "John Doe", "john.doe@example.com")
+```
+
+### Async vs Sync Assertions
+
+**IMPORTANT**: For async functions (using `AsyncMock`), use `assert_awaited...` methods:
+
+- `assert_awaited_once()` instead of `assert_called_once()`
+- `assert_awaited_once_with(args)` instead of `assert_called_once_with(args)`
+- `assert_not_awaited()` instead of `assert_not_called()`
+
+For sync functions (using `MagicMock`), use `assert_called...` methods:
+
+- `assert_called_once()`
+- `assert_called_once_with(args)`
+- `assert_not_called()`
+
+### Positive and Negative Assertions
+
+Always include both positive assertions (what should happen) and negative assertions (what should NOT happen) to ensure functions aren't being called unexpectedly.
+
+### Mocking
+
+As stated, `pytest_mock` should be used for mocking and all mocks should be defined as fixtures. Use `httpx` for HTTP clients and `respx` for mocking `httpx` calls in tests, with `respx` configured via pytest fixtures.
+
+Mocks should always be at most one level deep. i.e. if function a calls function b, and function b calls function c and you are testing function a, you should mock function b, not function c.
+
+#### Mock Fixture Naming
+
+Mock fixtures should be named `mock_<function_name>`, matching the function being patched. For example:
+
+```python
+# Patching ensure_account_has_stripe_customer_id
+@pytest.fixture
+def mock_ensure_account_has_stripe_customer_id(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("some_service.module.ensure_account_has_stripe_customer_id")
+
+# Patching invoke_lambda
+@pytest.fixture
+def mock_invoke_lambda(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("lambda_client.client.invoke_lambda")
+```
+
+**Exception: DynamoDB model functions.** Because `dynamodb_helper` model modules share common function names (`get_by_id`, `create`, `upsert`, etc.), mock fixtures for DynamoDB model functions must be prefixed with the table module name to avoid collisions: `mock_<module_name>_<function_name>`.
+
+```python
+# Two different get_by_id functions — module prefix disambiguates
+@pytest.fixture
+def mock_accounts_get_by_id(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("dynamodb_helper.models.accounts.get_by_id")
+
+@pytest.fixture
+def mock_patients_get_by_id(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("dynamodb_helper.models.patients.get_by_id")
+```
+
+#### Mock Fixture Placement
+
+Mock fixtures must be defined at module top-level (between imports and the first test class), never inside test classes. They should not be placed in `conftest.py` since they are path-specific. Only shared data fixtures belong in `conftest.py`.
+
+#### AWS Service Mocking
+
+When testing code that uses AWS services, follow this pattern (see [AWS Services](#aws-services-packagessrcawspy) section for the production abstraction):
+
+**Create AWS abstraction** (`src/package_name/aws.py`):
+
+```python
+from contextlib import asynccontextmanager
+from aioboto3 import Session
+
+session = Session()
+
+@asynccontextmanager
+async def get_s3():
+    async with session.client("s3") as s3_client:
+        yield s3_client
+```
+
+**Use abstraction in production code**:
+
+```python
+from package_name.aws import get_s3
+
+async def upload_file(bucket: str, key: str, content: bytes) -> None:
+    async with get_s3() as s3:
+        await s3.put_object(Bucket=bucket, Key=key, Body=content)
+```
+
+**Test with botocore stubber**:
+
+```python
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+import pytest
+from aioboto3 import Session
+from botocore.stub import Stubber
+from pytest_mock import MockerFixture, MockType
+
+@pytest.fixture(autouse=True)
+def fake_aws_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AWS_ACCESS_KEY_ID", "testing")
+    monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "testing")
+    monkeypatch.setenv("AWS_SESSION_TOKEN", "testing")
+    monkeypatch.setenv("AWS_DEFAULT_REGION", "us-east-2")
+
+@pytest.fixture
+def mock_get_s3(mocker: MockerFixture) -> MockType:
+    return mocker.patch("package_name.client.get_s3")
+
+@pytest.fixture
+async def s3_stub(mock_get_s3: MockType) -> AsyncGenerator[Stubber]:
+    session = Session()
+    async with session.client("s3", region_name="us-east-2") as s3_client:
+        stubber = Stubber(s3_client)
+        stubber.activate()
+
+        @asynccontextmanager
+        async def _fake_get_s3():
+            yield s3_client
+
+        mock_get_s3.side_effect = _fake_get_s3
+        yield stubber
+        stubber.assert_no_pending_responses()
+        stubber.deactivate()
+
+class TestUploadFile:
+    async def test_upload_success(self, s3_stub: Stubber):
+        s3_stub.add_response(
+            "put_object",
+            {},
+            {
+                "Bucket": "test-bucket",
+                "Key": "test-key",
+                "Body": b"test-content",
+            },
+        )
+
+        await upload_file("test-bucket", "test-key", b"test-content")
+```
+
+This `aws.py` file itself should be added to the `omit` list in the `pyproject.toml` file of the package. For example:
+
+```toml
+omit = [
+    "src/<package_name>/aws.py",
+]
+```
+
+### Running Tests
+
+```bash
+pnpm exec nx run <package-name>:test
+```
+
+### Fixtures
+
+#### Logger Fixture
+
+**IMPORTANT**: Always use a real `BioscopeLogger` instance in tests, not a mock. Create a `conftest.py` file in your package's test directory:
+
+```python
+import pytest
+from bioscope_logger import BioscopeLogger, get_logger
+from uuid import uuid4
+
+@pytest.fixture
+def logger() -> BioscopeLogger:
+    return get_logger("package-name", uuid4())
+```
+
+This fixture will be automatically available to all tests in the package. **Never** create individual logger fixtures using `AsyncMock` or `MagicMock` in test files - always use the real logger from conftest.py.
+
+#### Other Fixtures
+
+Example:
+
+```python
+from unittest.mock import AsyncMock, MagicMock
+from pytest_mock import MockerFixture
+from models import Patient
+
+@pytest.fixture
+def patient() -> Patient:
+    return Patient(
+        id="123",
+        name="John Doe",
+    )
+
+@pytest.fixture
+def mock_get_patient(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("some_service.utils.get_patient")
+
+@pytest.fixture
+def mock_sync_function(mocker: MockerFixture) -> MagicMock:
+    return mocker.patch("some_service.utils.sync_function")
+
+class TestMyFunction:
+    async def test_happy_path(self, patient: Patient, mock_get_patient: AsyncMock):
+        mock_get_patient.return_value = patient
+        # Use assert_awaited_once_with for async mocks
+        mock_get_patient.assert_awaited_once_with("patient_id")
+
+    def test_sync_function(self, mock_sync_function: MagicMock):
+        mock_sync_function.return_value = "result"
+        # Use assert_called_once_with for sync mocks
+        mock_sync_function.assert_called_once_with("arg")
+```
+
+**Fixture Type Guidelines**:
+
+- Use `MagicMock` for synchronous functions
+- Use `AsyncMock` for asynchronous functions
+- pytest-mock automatically creates the correct mock type, but explicit typing helps with IDE support
+
+### Test Coverage
+
+Always aim for 100% coverage. `#pragma: no cover` can be used to exclude specific lines from coverage.
+
+### Do NOT create `__init__.py` files in test directories
+
+You should NEVER create an `__init__.py` file in a test directory. Doing so will break the VSCode/Cursor test explorer.
+
+## Querying Logs in Axiom
+
+Use the Axiom MCP tools to query logs. If the Axiom MCP tools are not available, stop and ask the user to set up the Axiom MCP server in their Claude Code configuration before proceeding.
+
+Logs are in the `bioscope-dev` dataset for the dev AWS environment and the `bioscope-prod` dataset for the prod AWS environment. Axiom was enabled in prod on **2026-02-19**, so there are no prod logs before that date. Axiom uses APL (similar to Kusto/KQL). All field names are **camelCase**.
+
+### Key Fields
+
+| Field                                  | Description                                                |
+| -------------------------------------- | ---------------------------------------------------------- |
+| `_time`                                | Timestamp                                                  |
+| `logGroup`                             | CloudWatch log group (e.g., `/aws/lambda/account-service`) |
+| `message`                              | Log message                                                |
+| `levelname`                            | Log level (`INFO`, `ERROR`, etc.)                          |
+| `service`                              | Service name                                               |
+| `correlationId`                        | UUID for tracing requests across services                  |
+| `accountId`, `userId`, `patientId`     | Entity identifiers                                         |
+| `path`, `method`, `statusCode`, `took` | HTTP request details                                       |
+| `errorMessage`, `errorType`            | Error details                                              |
+| `data`                                 | Object containing extra fields not in the standard set     |
+
+### Example Queries
+
+```apl
+// Errors in a service
+['bioscope-dev']
+| where levelname == "ERROR" and logGroup == "/aws/lambda/account-service"
+
+// Trace a request across services
+['bioscope-dev']
+| where correlationId == "550e8400-e29b-41d4-a716-446655440000"
+| order by _time asc
+
+// Slow requests
+['bioscope-dev']
+| where took > 1000
+| project _time, service, path, took
+
+// Error counts by service (last hour)
+['bioscope-dev']
+| where _time > ago(1h) and levelname == "ERROR"
+| summarize count() by logGroup
+```6:["$","div","platform-services",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"platform-services"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/platform-services/AGENTS.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"AGENTS.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/platform-services/AGENTS.md"}]]}],["$","$L2",null,{"content":"$e","previewLines":8}]]}],"$Lf","$L10","$L11"]}]]}]
+12:Tc8a,# Web App - Claude Instructions
+
+## E2E Test Users
+
+### How test users are managed
+
+E2E tests use Auth0 users with the email pattern `success+test_user_N@simulator.amazonses.com` and password `test123!`. The user list is in `e2e/data/users.json`. Each developer (or worktree) reserves a slot of 25 users via the `E2E_USER_START_INDEX` env var in `.env.local` (see README for slot table).
+
+### How to add more test users
+
+Test users must be created in the Auth0 dashboard for the `bioscope-dev` tenant. There is no Management API key available — users must be created through the UI.
+
+**Steps per user:**
+
+1. Go to https://manage.auth0.com/dashboard/us/bioscope-dev/users
+2. Click "Create User" (dropdown) -> "Create via UI"
+3. Enter email: `success+test_user_N@simulator.amazonses.com`
+4. Enter password: `test123!`
+5. Click "Create" — this navigates to the User Details page
+6. Find the Email field (shows "UNVERIFIED") -> click "Edit"
+7. In the modal, click the "Set email as verified" link/button -> click "Save"
+8. Click "Back to Users" to return to the list
+9. Add the user to `e2e/data/users.json`
+
+**Important notes:**
+- The Auth0 dashboard is very slow. Allow 10-20 seconds between interactions.
+- "Set email as verified" is a clickable button/link in the Edit Email modal, not a checkbox.
+- Auth0 search indexing has a delay — newly created users may not appear in search immediately.
+- Do NOT use the app signup flow to create test users. It uses email verification codes and does not set a password.
+
+### How to test flows manually with a browser MCP server
+
+When using a browser MCP server (Playwright MCP, Chrome DevTools MCP, etc.) to manually test application flows against the dev environment:
+
+1. **Pick a test user from your slot.** Check your `E2E_USER_START_INDEX` in `.env.local` and pick a user within your 25-user range (e.g., if your start index is 50, use `success+test_user_51@simulator.amazonses.com` through `test_user_75`).
+
+2. **Clear the test user data before testing.** This resets the user to a clean state in the backend:
+   ```bash
+   curl -X POST https://api.dev.bioscope.ai/internal/test/clear-test-users \
+     -H "Content-Type: application/json" \
+     -H "Bioscope-Internal-Api-Key: Ug3jsqC73u72dw41Gnzn" \
+     -d '{"test_user_emails": ["success+test_user_N@simulator.amazonses.com"]}'
+   ```
+
+3. **Run your manual browser test.** Navigate to `https://app.dev.bioscope.ai` (or `http://localhost:5173` if testing local changes), log in with the test user email and `test123!`, and walk through the flow.
+
+4. **Clear the test user data after testing.** Run the same curl command from step 2 to clean up.
+
+## GitHub Actions
+
+All external GitHub Actions in workflow files must be pinned to commit SHAs, not version tags. Version tags are mutable and can be hijacked in a supply chain attack. Add the version as a comment for readability.
+
+```yaml
+# Good
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+# Bad
+- uses: actions/checkout@v4
+```
+
+Internal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.
+
+## Code Conventions
+
+- See `.claude/rules.md` for coding rules.
+- Never include PII/PHI in log metadata.7:["$","div","web-app",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"web-app"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/web-app/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/web-app/CLAUDE.md"}]]}],["$","$L2",null,{"content":"$12","previewLines":8}]]}],"$L13","$L14"]}]]}]
+15:T20f4,# WGS Ingestion Bot
+
+Slack bot that automatically investigates WGS ingestion failures using Claude Code.
+
+## Persona
+
+You are a bioinformatics engineer embedded in the Bioscope platform team. You have deep expertise in clinical WGS pipelines and are the on-call expert for ingestion failures. Assume your audience (the engineering team in Slack) has strong genomics and software knowledge -- do not over-explain standard concepts.
+
+### Domain Knowledge
+
+**Pipeline scope:** Bioscope runs 30x whole genome sequencing. The analysis is limited to single nucleotide variants (SNVs) and small insertions/deletions (INDELs, <1000bp). It does NOT detect or report: copy number variants (CNVs), structural variants (SVs), repeat expansions, HLA typing, or other complex variant types.
+
+**Ingestion pipeline stages (in order):**
+
+1. **Kit intake** -- GxG vendor integration, kit registration via `wgs_ingestion_service`
+2. **Raw data receipt** -- RAW_VCF, RAW_FASTQ, RAW_BAM artifacts land in S3
+3. **VCF processing** -- validation, quality filtering, invalid VCF detection (`vcf_processor`)
+4. **Iceberg partitioning** -- variant data written to Iceberg tables via Glue/Athena
+5. **WGS query** -- ClinVar + dbSNP annotation, high/low significance variant splitting (`genomics_wgs_query_service`)
+6. **Variant assessment** -- pathogenicity scoring, clinical significance classification, risk stratification, genomic tile generation (`genomics_variant_assessment_service`)
+7. **PRS processing** -- intermediate VCF generation, ancestry inference (6 populations: EUR, AFR, AMR, CSA, EAS, MID), polygenic risk score calculation across 36+ traits (`genomics_prs_processor`)
+8. **Blood typing** -- BAM subsetting, bloodAGENT phenotype prediction for ABO, RHD, and other blood group systems (`genomics_blood_type_service`)
+9. **Results delivery** -- event publishing, patient notification
+
+**Key services and their log groups:**
+
+| Service | Purpose |
+|---------|---------|
+| `wgs_ingestion_service` | Orchestrates the full pipeline via Step Functions |
+| `vcf_processor` | VCF validation and filtering |
+| `genomics_wgs_query_service` | Variant annotation with ClinVar/dbSNP, significance filtering |
+| `genomics_variant_assessment_service` | Clinical interpretation, tile generation |
+| `genomics_prs_processor` | Polygenic risk score calculation |
+| `genomics_prs_results_service` | PRS result retrieval and enrichment |
+| `genomics_blood_type_service` | Blood group phenotyping |
+| `genomics_bam_subset_processor` | BAM subsetting for blood typing |
+| `genomics_event_consumer` | WGS event processing |
+| `wgs_data_lineage_service` | Artifact traceability |
+
+
+**External databases:** ClinVar, dbSNP, ClinGen, MONDO (disease ontology), PGS Catalog
+
+**Infrastructure:** AWS -- S3 (artifacts), DynamoDB (metadata/tracking), Step Functions (orchestration), Glue (ETL), Athena (SQL over variants), Bedrock/Claude (LLM services via llm_proxy_service)
+
+### Communication Style
+
+- Be direct and technical. Lead with the finding, not the process.
+- When reporting failures, always identify: which pipeline stage failed, which service, and the relevant correlation/ingestion IDs.
+- Use standard genomics terminology without hedging (allele, zygosity, pathogenicity, etc.).
+- When a failure is ambiguous, state what you know, what you suspect, and what you would need to confirm -- do not speculate beyond the evidence in the logs.
+- Keep Slack replies concise. Save detail for the uploaded markdown report.
+
+## Tool Restrictions
+
+- NEVER use `ide - executeCode` or any IDE tools. Use the standard `Write` tool to create report files.
+- Write all reports to `./reports/` using the `Write` tool.
+- **CRITICAL**: If a tool call fails or is blocked due to permission restrictions, you MUST NOT hang waiting for terminal approval. Instead, IMMEDIATELY post a message to the Slack thread via `slack_reply` explaining what you tried to do and what permission is missing, then continue with the rest of the investigation. A silently blocked bot is useless -- always communicate status to Slack and keep moving.
+- **CRITICAL**: Before creating a Linear issue (`save_issue`), you MUST first ask for approval in the Slack thread. Post a message describing the issue you want to create (title, team, description) and explicitly ask "Should I create this ticket?" Then WAIT for the user to reply with confirmation before calling `save_issue`. Never create Linear issues without explicit user approval in Slack.
+
+## Setup
+
+Required environment variables (set in `.env`, which is gitignored):
+
+| Variable | Description |
+|----------|-------------|
+| `SLACK_APP_TOKEN` | Socket Mode app token (`xapp-...`) |
+| `SLACK_BOT_TOKEN` | Bot OAuth token (`xoxb-...`) |
+| `ALERT_CHANNEL_ID` | Slack channel ID for ingestion alerts |
+| `DM_CHANNEL_ID` | Slack channel ID for direct messaging with allowed users (optional) |
+| `PLATFORM_SERVICES_PATH` | Path to local platform-services checkout (optional, enables code cross-referencing) |
+| `INFRASTRUCTURE_PATH` | Path to local infrastructure checkout (optional, enables Terraform cross-referencing) |
+
+## Git Restrictions
+
+Agents must NEVER run `git add` or `git commit` commands. The user will handle all git staging and commits manually.
+
+## Code Quality
+
+- TypeScript (Bun runtime) for the channel plugin
+- No emojis or non-standard symbols in code or markdown
+
+## Channel Architecture
+
+Alerts flow through a Claude Code Channel plugin (`channel/server.ts`):
+
+1. Slack alert arrives via Socket Mode
+2. Channel plugin pushes it as a `notifications/claude/channel` event
+3. Claude dispatches a background Agent to run the investigation (see below)
+4. On completion, Claude uses `slack_reply` and `slack_upload_report` to post results back
+
+## Concurrent Investigations
+
+All alerts and human messages arrive in a single conversation. To stay responsive and handle multiple events in parallel, follow these rules:
+
+### Alert handling
+
+When an alert arrives, ALWAYS dispatch the investigation to a **background Agent** (`run_in_background: true`). Never run investigations inline in the main conversation.
+
+The background agent prompt MUST include:
+- The full alert text
+- The `channel_id` and `thread_ts` for Slack replies
+- Instructions to follow the `/investigate-wgs-ingestion` steps (paste or reference the full procedure)
+- A reminder that the agent cannot call `slack_reply` or `slack_upload_report` directly -- it should return the report file path and a summary so the main conversation can post them
+
+When the background agent completes:
+1. Read the report it wrote to `./reports/`
+2. Upload it to the Slack thread via `slack_upload_report`
+3. Post a summary via `slack_reply`
+
+### Human message handling
+
+Always respond to human messages directly in the main conversation -- do NOT delegate these to background agents. This keeps you immediately responsive to the user while investigations run in parallel.
+
+### Multiple concurrent alerts
+
+If 2+ alerts arrive before prior investigations finish, spawn a separate background agent for each. Each agent operates independently on its own alert.
+
+## Querying Logs in Axiom
+
+Logs are in the `bioscope-dev` dataset for the dev AWS environment and the `bioscope-prod` dataset for the prod AWS environment. Axiom uses APL (similar to Kusto/KQL). All field names are **camelCase**.
+
+### Key Fields
+
+| Field | Description |
+| ------- | ------------- |
+| `_time` | Timestamp |
+| `logGroup` | CloudWatch log group (e.g., `/aws/lambda/account-service`) |
+| `message` | Log message |
+| `levelname` | Log level (`INFO`, `ERROR`, etc.) |
+| `service` | Service name |
+| `correlationId` | UUID for tracing requests across services |
+| `accountId`, `userId`, `patientId` | Entity identifiers |
+| `path`, `method`, `statusCode`, `took` | HTTP request details |
+| `errorMessage`, `errorType` | Error details |
+| `data` | Object containing extra fields not in the standard set |
+
+### Example Queries
+
+```apl
+// Errors in a service
+['bioscope-dev']
+| where levelname == "ERROR" and logGroup == "/aws/lambda/account-service"
+
+// Trace a request across services
+['bioscope-dev']
+| where correlationId == "550e8400-e29b-41d4-a716-446655440000"
+| order by _time asc
+
+// Slow requests
+['bioscope-dev']
+| where took > 1000
+| project _time, service, path, took
+
+// Error counts by service (last hour)
+['bioscope-dev']
+| where _time > ago(1h) and levelname == "ERROR"
+| summarize count() by logGroup
+```8:["$","div","wgs-ingestion-bot",{"className":"mb-8","children":[["$","h2",null,{"className":"text-xs font-medium text-text-dim uppercase tracking-wide mb-3","children":"wgs-ingestion-bot"}],["$","div",null,{"className":"space-y-3","children":[["$","div","/Users/gabry/Desktop/wgs-ingestion-bot/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/wgs-ingestion-bot/CLAUDE.md"}]]}],["$","$L2",null,{"content":"$15","previewLines":8}]]}]]}]]}]
+9:["$","script","script-0",{"src":"/_next/static/chunks/12p3iqtw2ohfq.js","async":true}]
+a:["$","$L16",null,{"children":["$","$17",null,{"name":"Next.MetadataOutlet","children":"$@18"}]}]
+d:["$","div","/Users/gabry/Desktop/infrastructure/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/infrastructure/CLAUDE.md"}]]}],["$","$L2",null,{"content":"@AGENTS.md","previewLines":8}]]}]
+f:["$","div","/Users/gabry/Desktop/platform-services/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/platform-services/CLAUDE.md"}]]}],["$","$L2",null,{"content":"@AGENTS.md","previewLines":8}]]}]
+19:T7d63,# Platform Services Development Guide
+
+This is a Python monorepo using Nx and uv for managing dependencies and builds. Testing is done with pytest. Most packages are either deployed as AWS Lambda functions or shared libraries.
+
+## Project Structure
+
+This is a monorepo containing multiple Python packages that follow consistent patterns and conventions.
+
+## Account Types
+
+There are two account types, stored as `account_type` in the `accounts` DynamoDB table:
+
+- **`self-evaluation`** (aka "Try it on Yourself") — An individual signs up to evaluate Bioscope on themselves. They act as both the physician and the patient. One user, one patient, one-time payment. Paid if there's an active `selfEvaluationAccess` entitlement in the `account-entitlements` DynamoDB table.
+- **`practice`** — A practice with one or more physicians and potentially many patients. Has two billing models:
+  - **Enterprise** — created by a Bioscope employee, all billing is manual/out-of-band, all patients always considered paid. Identified by an `enterpriseProvisionedAccount` entitlement in the `account-entitlements` DynamoDB table.
+  - **Standard** — physician self-signs up, billing is per-patient via yearly subscriptions tracked in the `patient-entitlements` table.
+
+For full details, see the [Account Types and Billing Statuses](https://www.notion.so/Account-Types-and-Billing-Statuses-32713dc5995980a89921f096af7b57a5) Notion page (if you have access to Notion MCP).
+
+## GitHub Actions
+
+All external GitHub Actions in workflow files must be pinned to commit SHAs, not version tags. Version tags are mutable and can be hijacked in a supply chain attack. Add the version as a comment for readability.
+
+```yaml
+# Good
+- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+# Bad
+- uses: actions/checkout@v4
+```
+
+Internal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.
+
+## Dockerfile Dependency Installation
+
+All Dockerfiles must use lockfile-deterministic dependency installs. Never use `uv pip install -e` or `pip install -e` directly, as these resolve against PyPI at build time and ignore the lockfile.
+
+### Standard pattern (uv-based images)
+
+For Dockerfiles that use uv and target Python 3.13:
+
+```dockerfile
+# Export lockfile-pinned dependencies and install without resolution
+RUN uv export --frozen --no-dev --no-editable --package <package-name> -o /tmp/requirements.txt && \
+    uv pip install --system --no-deps -r /tmp/requirements.txt
+```
+
+This mirrors the Lambda bundler pattern (`bundle_lambda.py` / `bundle_layer.py`). The `--frozen` flag ensures exact versions from `uv.lock` are used, and `--no-deps` prevents any resolution against PyPI.
+
+### Non-uv base images (e.g., mriqc, fastsurfer)
+
+For Dockerfiles that extend specialized base images with a different Python version, install uv into the base image and use `uv sync` to create a Python 3.13 venv. The app runs on 3.13 while the base image's tools stay on their own Python:
+
+```dockerfile
+FROM <base-image>
+USER root
+WORKDIR /app
+
+RUN pip install --no-cache-dir "uv>=0.10.0,<0.11.0"
+
+COPY pyproject.toml uv.lock ./
+COPY packages/<workspace-deps>/ ./packages/<workspace-deps>/
+
+# Install Python under /app so non-root users can access it
+ENV UV_PYTHON_INSTALL_DIR=/app/.python
+RUN uv sync --frozen --no-dev --python 3.13 --package <package-name>
+
+ENTRYPOINT ["/app/.venv/bin/python", "-m", "<package_module>.main"]
+```
+
+### Non-workspace dependencies
+
+Any `pip install` of packages not managed by the workspace lockfile (e.g., `awscli` in utility images) must use an exact version pin (`==`). Unconstrained `pip install <package>` is not allowed.
+
+## Pull Request Guidelines
+
+### Cross-Repo Dependency Ordering
+
+`platform-services` (this repo) contains Python application code, while `infrastructure` provisions the AWS resources that the application code runs on. `platform-services` often depends on `infrastructure` changes. To avoid mistimed prod promotions breaking due to ordering, review PRs based on the following:
+
+If a code change in this repo introduces the **first usage** of an infrastructure-managed resource (DynamoDB table/index, S3 bucket, SQS queue, SNS topic, Secrets Manager secret, etc.), leave a comment asking the author to confirm that the corresponding `infrastructure` PR that provisions the resource is already merged and promoted to prod or to confirm that this is purely greenfield development that is not yet exposed to customers in the product.
+
+### Dependency Pinning
+
+All external package dependencies must use the compatible release operator (`~=`). Do not use `>=` as it leaves the version unbounded. Exact pins (`==`) are acceptable when a package requires a specific version.
+
+### Code Standards
+
+When reviewing code, ensure it adheres to the code standards guidelines outlined in the [README](./README.md), specifically with regard to mocking, Pydantic models, AWS service interaction, middleware usage, etc. It is ok to leave small, low-priority comments about code standards violations.
+
+It is also ABSOLUTELY CRITICAL to ensure that log statements do not contain PII/PHI data. Instead, use internal UUIDs to identify users, accounts, patients, resources, etc. See the [PII/PHI Logging Rules](#piiphi-logging-rules) section for the complete list of prohibited and safe fields.
+
+For logging, error handling, traceability, etc. it's also critical that any new lambda handler uses the standard `lambda-handler` package and the `BioscopeLogger` and that any new rest API lambda uses the standard `shared-middleware` package.
+
+### IDOR Prevention
+
+When reviewing route handlers, watch for authorization gaps that could allow users to access or modify resources belonging to other accounts/patients:
+
+- **Patient routes**: Any route with `{patient_id}` in the path must use `Depends(validate_patient_account_from_path_as_patient)` (from `shared_middleware`). This middleware calls account-service to verify the patient belongs to the requesting account. If a route takes a patient ID without this dependency and does not do patient validation internally, it's an IDOR vulnerability.
+- **Always use the validated patient result**: When a route uses `validate_patient_account_from_path_as_patient`, always name the dependency `patient` (never `_`). If the route also takes a sub-resource ID (e.g., `{chat_id}`, `{file_id}`), the service layer must verify that the fetched resource's `patient_id` matches `patient.patient_id`. Discarding the patient dependency with `_` is a red flag — it means the patient-to-resource ownership check is likely missing.
+- **Other resource routes**: Routes that fetch a resource by ID (e.g., orders, EHR connections) must verify `resource.account_id == account_id` before returning or mutating it. If the resource is patient-specific (contains a `patient_id` field), the route must also validate that `resource.patient_id == patient_id`.
+- **List/query endpoints**: Queries that return collections must scope by `account_id` (or `patient_id` where applicable) to prevent cross-account data leakage.
+- **Trusted headers**: The `Bioscope-Account-Id` and `Bioscope-User-Id` headers are validated by the API Gateway account authorizer and can be trusted for authorization checks. Use these (via `BioscopeAccountIdHeaderDeps`, `BioscopeUserIdHeaderDeps`), and NEVER trust account id or user id from path params, query params, or request bodies.
+
+### Billing Enforcement
+
+Any route that creates or modifies patient data or consumes metered resources (e.g., LLM tokens, test orders) must enforce billing via the billing validation middleware from `shared_middleware.billing_validation`:
+
+- **`ensure_patient_billing_access_from_path`**: Use when `patient_id` is a path parameter. Add as a `Depends()` dependency on the route.
+- **`ensure_patient_billing_access_from_body`**: Use when `patient_id` is in the request body (as `patientId` at the root level). Add as a `Depends()` dependency on the route.
+
+Both middlewares invoke account-service to check the account's billing entitlements and return a 403 with a specific denial reason if access is not granted. Read-only routes (listing, viewing) do not require billing enforcement.
+
+## Commands
+
+Nx commands are run with:
+
+```bash
+pnpm exec nx run <package-name>:<command>
+```
+
+For example, to run tests for the `dynamodb-helper` package:
+
+```bash
+pnpm exec nx run dynamodb-helper:test
+```
+
+Available commands are defined in `nx.json` at the root and in each package's `project.json` file.
+
+### Formatting, Linting, and Type Checking
+
+For code quality, ALWAYS run formatting, linting, and type checking after making changes. These are three separate commands — `format` and `lint` are NOT the same thing, even though both use `ruff` under the hood. `format` fixes code style (whitespace, line length, etc.) while `lint` catches code quality issues (unused imports, bad practices, etc.). ALWAYS run all three of the following commands after making changes:
+
+```bash
+pnpm exec nx run <package-name>:format
+pnpm exec nx run <package-name>:lint
+pnpm exec nx run <package-name>:type-check
+```
+
+**IMPORTANT**: You MUST run `format`, `lint`, and `type-check` commands (in addition to tests) after making changes to ensure your code is correct. Fix all formatting, linting, and type checking issues before considering the task complete.
+
+## Types
+
+This repo makes heavy use of Pydantic V2 models. Shared models are typically defined in the `bioscope-types` package.
+
+We have a `BioscopeBaseModel` class that is a subclass of `BaseModel` that adds some additional functionality, mostly adding camelCase aliases to the fields.
+In our code, we use snake_case for everything, but anything leaving or entering Python should be camelCase, for example:
+
+- Network requests and responses
+- Database rows
+- Logging statements
+
+The shared `BioscopeBaseModel` automatically takes care of this for us.
+
+## FastAPI Routes (`packages/**/src/**/routes/**.py`)
+
+### Basic Conventions
+
+- Route functions should be async
+- Router should have a common prefix per file
+- Follow standard REST conventions
+
+### Headers and Authentication
+
+These routes are configured with an AWS API Gateway. Most routes are secured with a custom lambda authorizer.
+
+This authorizer validates the Bearer JWT token and extracts the user ID from the token.
+Requests come in with a `Bioscope-Account-Id` header that contains the account ID.
+The authorizer ensures that the user in the JWT belongs to the account.
+This means that these headers are "safe" and guaranteed to be valid for the calling user.
+
+Therefore, authorization (i.e. to prevent IDOR, etc.) should be done via these headers.
+
+These headers can be injected into the route function as dependencies using the `BioscopeUserIdHeaderDeps` and `BioscopeAccountIdHeaderDeps` classes.
+
+### Models
+
+Request and response models should both be Pydantic models that inherit `BioscopeBaseModel`.
+`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.
+
+### Logging
+
+Routes should use the `BioscopeLoggerDeps` class to inject the logger into the route function.
+This logger is automatically configured to include the user ID and account ID in the log messages.
+
+#### PII/PHI Logging Rules
+
+**Fields that must NEVER be logged:**
+
+- Patient names, emails, phone numbers, addresses, dates of birth
+- Medical data (diagnoses, medications, lab results, clinical notes)
+- Full request/response bodies from external APIs (FHIR, EHR, lab vendors, etc.)
+- Webhook payloads (these often contain patient data or credentials)
+- Secrets, tokens, API keys, credentials — omit these entirely (no length hints either)
+- Template parameters that contain patient-facing content (e.g., SMS/email body text)
+
+**Safe fields that CAN be logged:**
+
+- Internal UUIDs: `patient_id`, `account_id`, `user_id`, `order_id`, `connection_id`, `correlation_id`
+- Status codes, HTTP methods, URL paths
+- Counts and lengths (e.g., number of records processed, response body length)
+- Template/event names, enum values, operation names
+- Durations, timestamps, retry counts
+
+**Redaction pattern** — when context about a sensitive value is needed for debugging, log a length hint instead of the value:
+
+```python
+# Good — log a length hint for debugging without exposing the value
+logger.info("received webhook", extra={"bodyLength": len(body)})
+
+# Good — log only safe identifiers
+logger.info("processing patient", extra={"patientId": patient_id, "accountId": account_id})
+
+# Bad — logs the entire webhook/response body (may contain PII/PHI)
+logger.info("received webhook", extra={"body": body})
+logger.info("API response", extra={"response": response.json()})
+```
+
+**Never log full request/response bodies** — log the status code and body length instead:
+
+```python
+# Good
+logger.info("FHIR response", extra={"statusCode": response.status_code, "bodyLength": len(response.content)})
+
+# Bad
+logger.info("FHIR response", extra={"body": response.json()})
+```
+
+**Exception messages** — do not embed API response text in exception messages, as these end up in logs via `logger.exception`:
+
+```python
+# Good
+raise ValueError(f"EHR API returned {response.status_code}")
+
+# Bad — response body may contain PHI
+raise ValueError(f"EHR API error: {response.text}")
+```
+
+#### Formatting
+
+Do not wrap values in `str()` when passing them as log `extra` fields. `BioscopeLogger` handles serialization automatically. For example, use `extra={"patientId": patient_id}`, not `extra={"patientId": str(patient_id)}`. With this in mind, you also do not need to JSON-stringify any logged models; you can pass in a Python dict to `extra` (though be careful that any logged models do not contain PII or PHI, per the rules above).
+
+```python
+# Good
+extra={"metric": usage_metric.model_dump()}
+
+# Bad
+extra={"metric": usage_metric.model_dump_json()}
+extra={"metric": json.dumps(usage_metric.model_dump())}
+```
+
+### HTTP Client
+
+`httpx` is our preferred HTTP client. Do not use `requests` or `aiohttp` for new code. If another external library requires `aiohttp` or `requests`, that is fine. An example of this is `slack-sdk` which requires `aiohttp`.
+
+When testing code that uses `httpx`, use `respx` for mocking. Use the **pytest fixture pattern for this**.
+
+### Relative Versus Absolute Imports
+
+Production code should always use absolute imports. For example:
+
+```python
+from account_service.models import Account  # GOOD
+from .models import Account  # BAD
+```
+
+However, test directories are not modules. They cannot and should not contain `__init__.py` files. Therefore, relative imports must be used in test directories. For example:
+
+```python
+from .conftest import build_data  # GOOD
+from tests.conftest import build_data  # BAD
+```
+
+### Error Handling
+
+Raise `HTTPException` with appropriate status code and detail message
+
+## Lambda Handlers (`packages/**/handler.py`)
+
+### Handler Types
+
+1. **LambdaHandler** - base handler for non-API Gateway functions
+2. **HttpHandler** - extends LambdaHandler with API Gateway support (requires `lambda-handler[api]`)
+
+### Lazy Loading Pattern
+
+Many lambdas serve both as direct invocation functions and API Gateway integrations. Loading Python modules can be slow (100s of milliseconds), especially with many Pydantic models. This impacts cold start time.
+
+**Solution**: Use lazy loading in `handler.py` files only. Load direct invocation handling code only when needed, and vice versa for API Gateway routes.
+
+**Example**:
+
+```python
+from lambda_handler.http_handler import HttpHandler
+
+def get_app():
+    from my_service.app import app  # noqa: PLC0415
+    return app
+
+handler = HttpHandler(get_app)
+
+@handler.direct_invocation()
+def handle_direct_invocation(event: DirectInvocationEvent, logger: BioscopeLogger):
+    from my_service.handlers.handler_one import handle_handler_one  # noqa: PLC0415
+    return handle_handler_one(event, logger)
+```
+
+**Important**:
+
+- Restrict lazy imports to `handler.py` only
+- Keep common imports (logger, types, handler framework) at module level
+- Use `# noqa: PLC0415` to suppress linting warnings
+- Never lazy load in business logic or service modules
+
+### Decorators
+
+| Event Source      | Decorator                    | Required kwarg         | Notes                                    |
+| ----------------- | ---------------------------- | ---------------------- | ---------------------------------------- |
+| SQS               | `@handler.sqs`               | `queue_name="<queue>"` |                                          |
+| SNS               | `@handler.sns`               | `topic_name="<topic>"` |                                          |
+| Direct Invocation | `@handler.direct_invocation` | N/A                    | Operation extracted from request model   |
+| Event Bridge      | `@handler.event_bridge`      | N/A                    | Handles all EventBridge events           |
+| API Gateway Auth  | `@handler.authorizer`        | N/A                    | For custom API Gateway authorizers       |
+| Health Check      | `@handler.health_check`      | N/A                    | Custom health check (built-in available) |
+
+**Notes**:
+
+- EventBridge and authorizer handlers do not use operation discriminators - they handle all events of their type sent to the function.
+- Direct invocation handlers automatically extract the `operation` from the request model's `operation` class attribute.
+- A built-in health check handler is automatically registered for all Lambda functions and responds to `{"operation": "healthCheck"}` requests.
+
+### Message Payloads
+
+• Define a Pydantic model that **inherits `BioscopeBaseModel`** for every distinct message body.
+• Models should be defined in the `bioscope_types` package under the `services` module.
+
+Always annotate the first parameter with the corresponding event model from `lambda_handler.models`, e.g. `SqsEvent[MyMessage]`.
+`MyMessage` should be a new Pydantic model that inherits `BioscopeBaseModel`.
+`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.
+
+### Dependency Injection
+
+Handler functions may declare these optional parameters which will be injected automatically:
+
+- `logger: BioscopeLogger` - the project-wide structured logger.
+- `context: LambdaContext` - the AWS Lambda context object.
+
+### Example (SQS)
+
+```python
+from lambda_handler.handler import LambdaHandler
+from lambda_handler.models.sqs import SqsEvent
+from bioscope_types.common import BioscopeBaseModel
+
+handler = LambdaHandler()
+
+class MySqsMessage(BioscopeBaseModel):
+    my_custom_field: str
+
+@handler.sqs(queue_name="my-queue")
+def handle_sqs_event(event: SqsEvent[MySqsMessage], logger, context):
+    logger.info("processing message", extra={"myCustomField": event.body.my_custom_field})
+```
+
+### Style Rules
+
+- Use **explicit type annotations** everywhere.
+- Keep handler bodies minimal; delegate business logic to service modules.
+- Use the provided `logger`, not `print`, for output.
+- Do not log PII/PHI data. Follow the [PII/PHI Logging Rules](#piiphi-logging-rules) in the FastAPI Routes section — the same rules apply to Lambda handlers. Never log full event bodies, external API responses, webhook payloads, tokens, API keys, credentials, or other secrets.
+
+### Handler Organization (`packages/**/src/**/handlers/**/*.py`)
+
+For services with many direct invocation handlers, organize them in a dedicated `handlers` directory rather than implementing the business logic directly in `handler.py`.
+
+### Structure
+
+```text
+src/
+  service_name/
+    handler.py          # Contains @handler.direct_invocation decorators
+    handlers/
+      __init__.py       # Exports all handler functions
+      handler_one.py    # Individual handler implementation
+      handler_two.py    # Individual handler implementation
+```
+
+### Handler Function Signature
+
+Handler functions should follow this standardized signature:
+
+```python
+async def handle_operation_name(
+    args: OperationArgs,
+    logger: BioscopeLogger,
+) -> OperationResponse:
+    # Implementation here
+```
+
+Where:
+
+- `args` is the operation's arguments model from `bioscope_types.services`
+- `logger` is the structured logger instance
+- Return type matches the operation's response model
+
+### Main Handler File
+
+The main `handler.py` file should delegate to the individual handlers:
+
+```python
+from service_name.handlers import handle_operation_name
+
+@handler.direct_invocation()
+async def operation_name_handler(
+    event: OperationRequest, parent_logger: BioscopeLogger
+) -> OperationResponse:
+    return await handle_operation_name(
+        args=event.args,
+        logger=parent_logger.child(
+            {
+                # Add relevant fields from event.args (in camelCase and avoiding PHI/PII)
+            }
+        ),
+    )
+```
+
+## AWS Services (`packages/**/src/**/aws.py`)
+
+**All** AWS service clients should be abstracted using context managers in a dedicated `aws.py` file. This pattern should be used for all AWS services **except** those with specialized helper packages (i.e. S3 via `s3_helper`, SQS via `queue_helper`, and DynamoDB via `dynamodb_helper`).
+
+### AWS Abstraction Pattern
+
+Create `src/package_name/aws.py`:
+
+```python
+from contextlib import asynccontextmanager
+from aioboto3 import Session
+
+session = Session()
+
+@asynccontextmanager
+async def get_service_name():
+    async with session.client("service-name") as client:
+        yield client
+```
+
+### Usage in Production Code
+
+```python
+from package_name.aws import get_service_name
+
+async def some_operation() -> None:
+    async with get_service_name() as client:
+        await client.some_api_call()
+```
+
+## Testing (`packages/**/tests/**/*.py`)
+
+### Basic Rules
+
+- Prefer **pytest** for all unit tests.
+- Use **botocore.stub.Stubber** for mocking AWS services (don't use `mock.patch` directly on the service) except in the `dynamodb_helper` package which uses `moto` for mocking.
+- Tests are all run with `asyncio_mode = "auto"` in `pyproject.toml`, so tests don't need to be marked as async individually.
+- **AVOID** asserting on logger calls except in very limited cases. Use a real BioscopeLogger instance (see Logger Fixture section) rather than mocking it. If you absolutely need to test logging behavior, use `caplog: pytest.LogCaptureFixture`. (see @bioscope_logger/README.md)
+- Use pytest fixtures for both mocking and for defining common test data.
+- Test all cases for 100% test coverage, but don't overdo it with tests. And don't waste time testing code that is not written by us; i.e. don't write a test that effectively tests a library.
+- Under **no circumstances** should you write large amounts of code in a test file and then write tests that effectively test that code instead of the code in the actual production file.
+
+### Test Structure
+
+- Mirror source code structure in test organization
+- Individual classes for each function being tested
+- Individual methods for each test case
+
+Example:
+
+```python
+class TestCopyS3ToTemp:
+    def test_happy_path(self):
+        pass
+
+    def test_invalid_url_format(self):
+        pass
+
+    def test_s3_error(self):
+        pass
+```
+
+### Assertions
+
+When performing assertions on data, compare the entire object as much as possible rather than individual assertions for each field.
+
+For example, instead of:
+
+```python
+assert result is not None
+assert len(result) == 1
+assert result[0].id == "123"
+assert result[0].name == "John Doe"
+assert result[0].email == "john.doe@example.com"
+```
+
+you should do:
+
+```python
+assert result == [User(
+    id="123",
+    name="John Doe",
+    email="john.doe@example.com"
+)]
+```
+
+When performing assertions on what functions were called with, use the built in assert calls like `assert_called_once_with` rather than checking the arguments directly.
+For example, instead of:
+
+```python
+assert mock_foo.call_args.args == ("123", "John Doe", "john.doe@example.com")
+```
+
+you should do:
+
+```python
+mock_foo.assert_called_once_with("123", "John Doe", "john.doe@example.com")
+```
+
+### Async vs Sync Assertions
+
+**IMPORTANT**: For async functions (using `AsyncMock`), use `assert_awaited...` methods:
+
+- `assert_awaited_once()` instead of `assert_called_once()`
+- `assert_awaited_once_with(args)` instead of `assert_called_once_with(args)`
+- `assert_not_awaited()` instead of `assert_not_called()`
+
+For sync functions (using `MagicMock`), use `assert_called...` methods:
+
+- `assert_called_once()`
+- `assert_called_once_with(args)`
+- `assert_not_called()`
+
+### Positive and Negative Assertions
+
+Always include both positive assertions (what should happen) and negative assertions (what should NOT happen) to ensure functions aren't being called unexpectedly.
+
+### Mocking
+
+As stated, `pytest_mock` should be used for mocking and all mocks should be defined as fixtures. Use `httpx` for HTTP clients and `respx` for mocking `httpx` calls in tests, with `respx` configured via pytest fixtures.
+
+Mocks should always be at most one level deep. i.e. if function a calls function b, and function b calls function c and you are testing function a, you should mock function b, not function c.
+
+#### AWS Service Mocking
+
+When testing code that uses AWS services, follow this pattern (see [AWS Services](#aws-services-packagessrcawspy) section for the production abstraction):
+
+**Create AWS abstraction** (`src/package_name/aws.py`):
+
+```python
+from contextlib import asynccontextmanager
+from aioboto3 import Session
+
+session = Session()
+
+@asynccontextmanager
+async def get_s3():
+    async with session.client("s3") as s3_client:
+        yield s3_client
+```
+
+**Use abstraction in production code**:
+
+```python
+from package_name.aws import get_s3
+
+async def upload_file(bucket: str, key: str, content: bytes) -> None:
+    async with get_s3() as s3:
+        await s3.put_object(Bucket=bucket, Key=key, Body=content)
+```
+
+**Test with botocore stubber**:
+
+```python
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+import pytest
+from aioboto3 import Session
+from botocore.stub import Stubber
+from pytest_mock import MockerFixture, MockType
+
+@pytest.fixture(autouse=True)
+def fake_aws_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AWS_ACCESS_KEY_ID", "testing")
+    monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "testing")
+    monkeypatch.setenv("AWS_SESSION_TOKEN", "testing")
+    monkeypatch.setenv("AWS_DEFAULT_REGION", "us-east-2")
+
+@pytest.fixture
+def mock_get_s3(mocker: MockerFixture) -> MockType:
+    return mocker.patch("package_name.client.get_s3")
+
+@pytest.fixture
+async def s3_stub(mock_get_s3: MockType) -> AsyncGenerator[Stubber]:
+    session = Session()
+    async with session.client("s3", region_name="us-east-2") as s3_client:
+        stubber = Stubber(s3_client)
+        stubber.activate()
+
+        @asynccontextmanager
+        async def _fake_get_s3():
+            yield s3_client
+
+        mock_get_s3.side_effect = _fake_get_s3
+        yield stubber
+        stubber.assert_no_pending_responses()
+        stubber.deactivate()
+
+class TestUploadFile:
+    async def test_upload_success(self, s3_stub: Stubber):
+        s3_stub.add_response(
+            "put_object",
+            {},
+            {
+                "Bucket": "test-bucket",
+                "Key": "test-key",
+                "Body": b"test-content",
+            },
+        )
+
+        await upload_file("test-bucket", "test-key", b"test-content")
+```
+
+This `aws.py` file itself should be added to the `omit` list in the `pyproject.toml` file of the package. For example:
+
+```toml
+omit = [
+    "src/<package_name>/aws.py",
+]
+```
+
+### Running Tests
+
+```bash
+pnpm exec nx run <package-name>:test
+```
+
+### Fixtures
+
+#### Logger Fixture
+
+**IMPORTANT**: Always use a real `BioscopeLogger` instance in tests, not a mock. Create a `conftest.py` file in your package's test directory:
+
+```python
+import pytest
+from bioscope_logger import BioscopeLogger, get_logger
+from uuid import uuid4
+
+@pytest.fixture
+def logger() -> BioscopeLogger:
+    return get_logger("package-name", uuid4())
+```
+
+This fixture will be automatically available to all tests in the package. **Never** create individual logger fixtures using `AsyncMock` or `MagicMock` in test files - always use the real logger from conftest.py.
+
+#### Other Fixtures
+
+Example:
+
+```python
+from unittest.mock import AsyncMock, MagicMock
+from pytest_mock import MockerFixture
+from models import Patient
+
+@pytest.fixture
+def patient() -> Patient:
+    return Patient(
+        id="123",
+        name="John Doe",
+    )
+
+@pytest.fixture
+def mock_get_patient(mocker: MockerFixture) -> AsyncMock:
+    return mocker.patch("some_service.utils.get_patient")
+
+@pytest.fixture
+def mock_sync_function(mocker: MockerFixture) -> MagicMock:
+    return mocker.patch("some_service.utils.sync_function")
+
+class TestMyFunction:
+    async def test_happy_path(self, patient: Patient, mock_get_patient: AsyncMock):
+        mock_get_patient.return_value = patient
+        # Use assert_awaited_once_with for async mocks
+        mock_get_patient.assert_awaited_once_with("patient_id")
+
+    def test_sync_function(self, mock_sync_function: MagicMock):
+        mock_sync_function.return_value = "result"
+        # Use assert_called_once_with for sync mocks
+        mock_sync_function.assert_called_once_with("arg")
+```
+
+**Fixture Type Guidelines**:
+
+- Use `MagicMock` for synchronous functions
+- Use `AsyncMock` for asynchronous functions
+- pytest-mock automatically creates the correct mock type, but explicit typing helps with IDE support
+
+### Test Coverage
+
+Always aim for 100% coverage. `#pragma: no cover` can be used to exclude specific lines from coverage.
+
+### Do NOT create `__init__.py` files in test directories
+
+You should NEVER create an `__init__.py` file in a test directory. Doing so will break the VSCode/Cursor test explorer.
+
+## Querying Logs in Axiom
+
+Use the Axiom MCP tools to query logs. If the Axiom MCP tools are not available, stop and ask the user to set up the Axiom MCP server in their Claude Code configuration before proceeding.
+
+Logs are in the `bioscope-dev` dataset for the dev AWS environment and the `bioscope-prod` dataset for the prod AWS environment. Axiom was enabled in prod on **2026-02-19**, so there are no prod logs before that date. Axiom uses APL (similar to Kusto/KQL). All field names are **camelCase**.
+
+### Key Fields
+
+| Field                                  | Description                                                |
+| -------------------------------------- | ---------------------------------------------------------- |
+| `_time`                                | Timestamp                                                  |
+| `logGroup`                             | CloudWatch log group (e.g., `/aws/lambda/account-service`) |
+| `message`                              | Log message                                                |
+| `levelname`                            | Log level (`INFO`, `ERROR`, etc.)                          |
+| `service`                              | Service name                                               |
+| `correlationId`                        | UUID for tracing requests across services                  |
+| `accountId`, `userId`, `patientId`     | Entity identifiers                                         |
+| `path`, `method`, `statusCode`, `took` | HTTP request details                                       |
+| `errorMessage`, `errorType`            | Error details                                              |
+| `data`                                 | Object containing extra fields not in the standard set     |
+
+### Example Queries
+
+```apl
+// Errors in a service
+['bioscope-dev']
+| where levelname == "ERROR" and logGroup == "/aws/lambda/account-service"
+
+// Trace a request across services
+['bioscope-dev']
+| where correlationId == "550e8400-e29b-41d4-a716-446655440000"
+| order by _time asc
+
+// Slow requests
+['bioscope-dev']
+| where took > 1000
+| project _time, service, path, took
+
+// Error counts by service (last hour)
+['bioscope-dev']
+| where _time > ago(1h) and levelname == "ERROR"
+| summarize count() by logGroup
+```10:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/AGENTS.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"AGENTS.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/ps-copy/platform-services/AGENTS.md"}]]}],["$","$L2",null,{"content":"$19","previewLines":8}]]}]
+11:["$","div","/Users/gabry/Desktop/ps-copy/platform-services/CLAUDE.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"CLAUDE.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/ps-copy/platform-services/CLAUDE.md"}]]}],["$","$L2",null,{"content":"@AGENTS.md","previewLines":8}]]}]
+1a:T1ea2,# Claude Code Rules for Bioscope Web App
+
+## Design System and Styling
+
+### Color Usage
+**NEVER hardcode color values in components.** All colors must be defined in the design system.
+
+- ❌ **WRONG**: `bg-[#181f2e]`, `border-[#303a48]`, `text-[#8fbecc]`
+- ✅ **CORRECT**: `bg-tab-nav-background`, `border-tab-nav-border`, `text-tab-active-indicator`
+
+#### Process for Adding New Colors:
+1. Add the color variable to `@theme inline` section in `src/index.css`:
+   ```css
+   --color-new-color-name: var(--new-color-name);
+   ```
+
+2. Add the oklch value to `:root` section in `src/index.css`:
+   ```css
+   --new-color-name: oklch(L C H);
+   ```
+
+3. Use the Tailwind class in components:
+   ```tsx
+   className="bg-new-color-name"
+   ```
+
+#### Color Conversion:
+When converting hex colors to oklch:
+- Use online tools or color conversion utilities
+- Maintain the exact visual appearance
+- Document the original hex value in a comment if needed
+
+### Component Styling Guidelines
+- Always use the existing design system tokens
+- Check `src/index.css` for available color variables before adding new ones
+- Prefer semantic color names (e.g., `tab-nav-background`) over generic names (e.g., `dark-blue-1`)
+- Follow the existing naming conventions in the design system
+
+### Typography
+**Always use the Typography component for text rendering.** Never use raw HTML text elements or hardcoded font styles.
+
+#### Typography Component Usage
+The Typography component is located at `src/components/base/typography.tsx` and should be used for all text:
+
+```tsx
+import { Typography } from "@/components/base/typography";
+
+<Typography variant="section-title" color="primary">
+  My Text
+</Typography>
+```
+
+#### Available Typography Variants
+- `header` - Semibold 20px, for main headers
+- `large-title` - Semibold 20px, for large titles
+- `section-title` - Semibold 16px, for section headers
+- `section-content` - Normal 14px, for section body text
+- `attribute-label` - Normal 16px, for attribute labels
+- `key-value-key` - Semibold 14px, for key-value pair keys
+- `key-value-value` - Normal 14px, for key-value pair values
+- `button-label` - Bold 14px, for button text
+- `chip-label` - Medium 12px, for chip/badge text
+- `input-label` - Medium 14px, for form input labels
+- `input-helper` - Normal 12px, for input helper text
+- `input-text` - Medium 16px, for input field text
+- `detail-label` - Medium 12px, for detail labels
+- `detail-subtext` - Normal 12px, for detail subtext
+- `table-header` - Light 12px, for table headers
+- `table-cell` - Normal 14px, for table cells
+- `list-button-label` - Normal 20px, for list button labels
+
+#### Available Typography Colors
+- `primary` - Primary text color (text-text-primary)
+- `muted` - Muted text color (text-text-muted)
+- `error` - Error/destructive text color (text-destructive)
+- `secondary` - Secondary foreground color (text-secondary-foreground)
+
+#### When Typography Component Cannot Be Used
+In cases where you cannot use the Typography component directly (e.g., in custom components that need to apply typography styles to existing elements), use `typographyVariants`:
+
+```tsx
+import { typographyVariants } from "@/components/base/typography";
+import { cn } from "@/utils/cn";
+
+<SomeComponent
+  className={cn(typographyVariants({ variant: "section-title", color: "primary" }))}
+/>
+```
+
+#### Typography Props
+- `variant` - The typography variant to use (required for consistent styling)
+- `color` - The text color (defaults to primary if not specified)
+- `as` - The HTML element to render (p, span, div, h1-h6, li, pre, code, td, th)
+- `italic` - Boolean flag to apply italic styling
+- `className` - Additional custom classes (use sparingly)
+- `onClick` - Click handler (will add cursor-pointer automatically)
+- `testId` - Test ID for testing purposes
+
+#### Examples
+```tsx
+// Section header
+<Typography variant="section-title" color="primary">
+  User Information
+</Typography>
+
+// Body text
+<Typography variant="section-content" color="muted">
+  This is the description text.
+</Typography>
+
+// Error message
+<Typography variant="input-helper" color="error">
+  This field is required
+</Typography>
+
+// Custom element with typography styles
+<Typography variant="header" as="h1">
+  Page Title
+</Typography>
+
+// When Typography component cannot be used
+<CustomButton
+  className={cn(typographyVariants({ variant: "button-label", color: "primary" }))}
+>
+  Click Me
+</CustomButton>
+```
+
+## Project Structure
+
+### Directory Organization
+```
+src/
+├── assets/          # All static assets
+├── components/      # All reusable components
+│   └── base/        # Basic building blocks (buttons, accordions, etc.)
+│       └── shadcn/  # Shadcn registry components (DO NOT modify or export)
+├── hooks/           # Application-wide hooks
+│   └── api/         # API interaction and TanStack Query hooks
+└── pages/           # Full page components
+```
+
+### Component Structure
+
+#### Simple Components
+Simple, atomic components (like buttons) can be a single file:
+```
+button.tsx
+```
+
+#### Complex Components
+Complex components should be organized in directories with subcomponents:
+```
+Select/
+├── index.tsx        # Main component, exports only what consumers need
+├── hooks/           # Component-specific hooks
+├── utils/           # Component-specific utilities
+└── SelectOption.tsx # Sub-components
+```
+
+### Component Placement
+- Even single-use components should go in `src/components/` if not obviously scoped to a single page
+- Keep components small and composable
+- Avoid code duplication within components
+
+## React and TypeScript
+
+### Component Code Layout
+All custom (non-shadcn) components should follow this layout:
+
+```tsx
+import * as React from "react";
+
+type <ComponentName>OwnProps = {
+  // Component-specific props
+};
+
+export type <ComponentName>Props = {} & <ComponentName>OwnProps;
+
+function <ComponentName>Component({}: <ComponentName>Props) {
+  // Component implementation
+}
+
+const <ComponentName> = React.memo(<ComponentName>Component);
+
+export { <ComponentName> };
+```
+
+### Naming Conventions
+- **Files**: camelCase (e.g., `loadingContent.tsx`)
+- **Components**: PascalCase (e.g., `LoadingContent`)
+- **Index files**: Component takes parent directory name (e.g., `loadingContent/index.tsx` → `LoadingContent`)
+
+### Type Imports
+When using TypeScript with `verbatimModuleSyntax` enabled:
+- ✅ **CORRECT**: `import type { TypeName } from './module';`
+- ❌ **WRONG**: `import { TypeName } from './module';` (for types)
+
+### Hook Usage
+- Use hooks and custom hooks as needed
+- **Avoid `useRef` and `useEffect` unless absolutely necessary** - they can introduce bugs and hard-to-reason render cycles
+- When needing `useEffect`, consider using hooks from [react-use](https://github.com/streamich/react-use) for more direct, obvious, and opinionated code flow
+
+### Navigation
+- Always use `void navigate()` to handle promise returns from React Router
+- Mark button types explicitly: `<button type="button">`
+
+### Shadcn Components
+**CRITICAL**: Shadcn components live in `src/components/base/shadcn/` and have strict usage rules:
+
+- ❌ **NEVER** modify shadcn components
+- ❌ **NEVER** export shadcn components from `src/components/base/`
+- ❌ **NEVER** import shadcn components directly outside of `src/components/base/`
+- ✅ **ALWAYS** create a wrapper in `src/components/base/` for shadcn components before using them
+
+Example:
+```tsx
+// src/components/base/button.tsx
+import { Button as ShadcnButton } from "./shadcn/button";
+
+export function Button(props) {
+  return <ShadcnButton {...props} />;
+}
+```
+
+## General Code Quality
+- Follow existing patterns in the codebase
+- Use memoization for expensive computations
+- Ensure accessibility (ARIA labels, semantic HTML)
+- Test mobile responsiveness for all UI components13:["$","div","/Users/gabry/Desktop/web-app/.clauderules",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":".clauderules"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/web-app/.clauderules"}]]}],["$","$L2",null,{"content":"$1a","previewLines":8}]]}]
+1b:T6de,# Claude Development Rules
+
+## Component Organization
+
+### Multiple Components Per File
+
+**Rule**: Do not place multiple components in the same file. Each component should be organized into its own directory structure.
+
+**Structure**: When a component contains sub-components or helper functions:
+
+1. Create a directory with the component name
+2. Create an `index.tsx` file for the main component export
+3. Create separate files for each sub-component
+4. Create a `utils.ts` file for helper functions and utilities
+
+**Example**:
+
+```
+ComponentName/
+├── index.tsx           # Main component export
+├── SubComponentA.tsx   # Sub-component A
+├── SubComponentB.tsx   # Sub-component B
+└── utils.ts            # Helper functions
+```
+
+**Benefits**:
+
+- Improved code organization and maintainability
+- Easier to locate and modify specific components
+- Better separation of concerns
+- Cleaner git diffs and easier code reviews
+- Simpler testing of individual components
+
+**Bad Example** ❌:
+
+```tsx
+// MyModal.tsx
+export function MyModal() { ... }
+function ModalHeader() { ... }
+function ModalBody() { ... }
+function formatDate() { ... }
+```
+
+**Good Example** ✅:
+
+```
+MyModal/
+├── index.tsx          # exports MyModal
+├── ModalHeader.tsx    # exports ModalHeader
+├── ModalBody.tsx      # exports ModalBody
+└── utils.ts           # exports formatDate
+```
+
+## Logging and Event Tracking
+
+**Rule:** Never send anything to the client logging service (src/utils/logger.ts) that might contain user PII or PHI. Ensure that only IDs are used to identify an account, user, or patient, and only include the bare minimum of information to capture vital data for troubleshooting an error or identifying an event or user action.14:["$","div","/Users/gabry/Desktop/web-app/.claude/rules.md",{"className":"border border-border rounded-sm p-5 ","children":[["$","div",null,{"className":"flex items-center gap-2 mb-2","children":[["$","span",null,{"className":"inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted","children":"rules.md"}],["$","span",null,{"className":"text-xs text-text-dim font-mono","children":"/Users/gabry/Desktop/web-app/.claude/rules.md"}]]}],["$","$L2",null,{"content":"$1b","previewLines":8}]]}]
+18:null