npm - miclaw-app - Versions diffs - 0.1.0 - Mend

miclaw-app 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1324) hide show

package/.next/standalone/.next/server/app/rules.html ADDED Viewed

@@ -0,0 +1,72 @@
+<!DOCTYPE html><html lang="en" class="inter_fe8b9d92-module__LINzvG__variable geist_mono_8d43a2aa-module__8Li5zG__variable fira_code_d18ac710-module__OladcG__variable"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" href="/_next/static/media/166ab60e98aadb0a-s.p.0mka4ru4_bj1d.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/797e433ab948586e-s.p.0.q-h669a_dqa.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="preload" href="/_next/static/media/83afe278b6a6bb3c-s.p.0q-301v4kxxnr.woff2" as="font" crossorigin="" type="font/woff2"/><link rel="stylesheet" href="/_next/static/chunks/0iym2_f33sxs7.css" data-precedence="next"/><link rel="preload" as="script" fetchPriority="low" href="/_next/static/chunks/0bzupvr5gt3k9.js"/><script src="/_next/static/chunks/0y3~cortx~or~.js" async=""></script><script src="/_next/static/chunks/0bogtdbh.dcu1.js" async=""></script><script src="/_next/static/chunks/turbopack-06dy8k5p5cegf.js" async=""></script><script src="/_next/static/chunks/0mmpyn9fv2fjf.js" async=""></script><script src="/_next/static/chunks/0d3shmwh5_nmn.js" async=""></script><script src="/_next/static/chunks/12p3iqtw2ohfq.js" async=""></script><meta name="next-size-adjust" content=""/><title>MiClaw</title><meta name="description" content="Claude Code configuration visualizer"/><link rel="icon" href="/favicon.ico?favicon.0x3dzn~oxb6tn.ico" sizes="256x256" type="image/x-icon"/><script src="/_next/static/chunks/03~yq9q893hmn.js" noModule=""></script></head><body class="bg-surface text-text font-sans antialiased"><div hidden=""><!--$--><!--/$--></div><div class="flex h-screen overflow-hidden"><nav class="w-16 shrink-0 border-r border-border py-4 flex flex-col items-center gap-2 overflow-visible"><a class="mb-3" style="writing-mode:vertical-lr" href="/"><span class="text-sm font-bold tracking-wider" style="font-family:var(--font-fira-code), monospace"><span class="text-text-muted">Mi</span><span class="text-accent">Claw</span></span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard" aria-hidden="true"><rect width="7" height="9" x="3" y="3" rx="1"></rect><rect width="7" height="5" x="14" y="3" rx="1"></rect><rect width="7" height="9" x="14" y="12" rx="1"></rect><rect width="7" height="5" x="3" y="16" rx="1"></rect></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Overview</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/agents"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-bot" aria-hidden="true"><path d="M12 8V4H8"></path><rect width="16" height="12" x="4" y="8" rx="2"></rect><path d="M2 14h2"></path><path d="M20 14h2"></path><path d="M15 13v2"></path><path d="M9 13v2"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Agents</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/skills"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-zap" aria-hidden="true"><path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Skills</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/commands"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-terminal" aria-hidden="true"><path d="M12 19h8"></path><path d="m4 17 6-6-6-6"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Commands</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/mcp"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-plug" aria-hidden="true"><path d="M12 22v-5"></path><path d="M15 8V2"></path><path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z"></path><path d="M9 8V2"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">MCP Servers</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/hooks"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-webhook" aria-hidden="true"><path d="M18 16.98h-5.99c-1.1 0-1.95.94-2.48 1.9A4 4 0 0 1 2 17c.01-.7.2-1.4.57-2"></path><path d="m6 17 3.13-5.78c.53-.97.1-2.18-.5-3.1a4 4 0 1 1 6.89-4.06"></path><path d="m12 6 3.13 5.73C15.66 12.7 16.9 13 18 13a4 4 0 0 1 0 8"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Hooks</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-text-dim hover:text-text hover:bg-surface-hover" href="/settings"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-shield" aria-hidden="true"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Settings</span></a><a class="relative group w-10 h-10 flex items-center justify-center rounded-md transition-colors
+              text-accent bg-surface-raised" href="/rules"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-file-text" aria-hidden="true"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z"></path><path d="M14 2v5a1 1 0 0 0 1 1h5"></path><path d="M10 9H8"></path><path d="M16 13H8"></path><path d="M16 17H8"></path></svg><span class="absolute left-full ml-3 px-2.5 py-1 rounded-md bg-surface-raised border border-border text-text text-xs font-medium whitespace-nowrap opacity-0 pointer-events-none group-hover:opacity-100 transition-opacity z-50 shadow-lg">Rules</span></a></nav><main class="flex-1 overflow-y-auto bg-grid"><div class="mx-auto max-w-5xl px-8 py-10"><div class="mb-8"><div class="flex items-baseline gap-3"><h1 class="text-2xl font-medium tracking-tight">Rules and Instructions</h1><span class="text-sm text-text-muted">12</span></div><p class="mt-1 text-sm text-text-muted">Repo instruction files that guide agent behavior</p></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">Desktop</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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 &quot;✓|✗|☐|○&quot; when writing code or markdown
+- Use parametrized tests whenever possible
+- Listed below are a handful of different &#x27;Workflow&#x27; guides. Adhere to them as best as possible<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div></div></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">ROADMAP_2026</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/ROADMAP_2026/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># Bioscope Bioinformatics 2026 Roadmap
+## Project Overview
+Interactive roadmap visualization tool for Bioscope Bioinformatics&#x27; 2026 strategic planning. Single-page web app with a Node.js backend for data persistence.
+## Files
+| File | Purpose |<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div></div></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">infrastructure</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">AGENTS.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/infrastructure/AGENTS.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># Repository Standards
+## CRITICAL SAFETY RULES
+**NEVER RUN APPLIES**
+Claude can ONLY run the following commands. All apply operations must be performed by humans.
+```bash<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/infrastructure/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed">@AGENTS.md</pre></div></div></div></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">platform-services</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">AGENTS.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/platform-services/AGENTS.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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.
+<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/platform-services/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed">@AGENTS.md</pre></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">AGENTS.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/ps-copy/platform-services/AGENTS.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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.
+<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/ps-copy/platform-services/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed">@AGENTS.md</pre></div></div></div></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">web-app</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/web-app/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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).
+<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">.clauderules</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/web-app/.clauderules</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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]`<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">rules.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/web-app/.claude/rules.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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.
+<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div></div></div><div class="mb-8"><h2 class="text-xs font-medium text-text-dim uppercase tracking-wide mb-3">wgs-ingestion-bot</h2><div class="space-y-3"><div class="border border-border rounded-sm p-5 "><div class="flex items-center gap-2 mb-2"><span class="inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-sm bg-surface-raised text-text-muted">CLAUDE.md</span><span class="text-xs text-text-dim font-mono">/Users/gabry/Desktop/wgs-ingestion-bot/CLAUDE.md</span></div><div class="mt-3"><pre class="text-xs text-text-muted font-mono whitespace-pre-wrap leading-relaxed"># 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.
+<span class="text-text-dim">...</span></pre><button class="mt-2 text-xs text-accent hover:text-accent-dim transition-colors">Show more</button></div></div></div></div></div><!--$--><!--/$--></main></div><script src="/_next/static/chunks/0bzupvr5gt3k9.js" id="_R_" async=""></script><script>(self.__next_f=self.__next_f||[]).push([0])</script><script>self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[22140,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"Sidebar\"]\n3:I[39756,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"default\"]\n4:I[37457,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"default\"]\n6:I[97367,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"OutletBoundary\"]\n7:\"$Sreact.suspense\"\na:I[97367,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"ViewportBoundary\"]\nc:I[97367,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"MetadataBoundary\"]\ne:I[68027,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"default\",1]\n:HL[\"/_next/static/chunks/0iym2_f33sxs7.css\",\"style\"]\n:HL[\"/_next/static/media/166ab60e98aadb0a-s.p.0mka4ru4_bj1d.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/797e433ab948586e-s.p.0.q-h669a_dqa.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n:HL[\"/_next/static/media/83afe278b6a6bb3c-s.p.0q-301v4kxxnr.woff2\",\"font\",{\"crossOrigin\":\"\",\"type\":\"font/woff2\"}]\n"])</script><script>self.__next_f.push([1,"0:{\"P\":null,\"c\":[\"\",\"rules\"],\"q\":\"\",\"i\":false,\"f\":[[[\"\",{\"children\":[\"rules\",{\"children\":[\"__PAGE__\",{}]}]},\"$undefined\",\"$undefined\",16],[[\"$\",\"$1\",\"c\",{\"children\":[[[\"$\",\"link\",\"0\",{\"rel\":\"stylesheet\",\"href\":\"/_next/static/chunks/0iym2_f33sxs7.css\",\"precedence\":\"next\",\"crossOrigin\":\"$undefined\",\"nonce\":\"$undefined\"}],[\"$\",\"script\",\"script-0\",{\"src\":\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"async\":true,\"nonce\":\"$undefined\"}],[\"$\",\"script\",\"script-1\",{\"src\":\"/_next/static/chunks/0d3shmwh5_nmn.js\",\"async\":true,\"nonce\":\"$undefined\"}]],[\"$\",\"html\",null,{\"lang\":\"en\",\"className\":\"inter_fe8b9d92-module__LINzvG__variable geist_mono_8d43a2aa-module__8Li5zG__variable fira_code_d18ac710-module__OladcG__variable\",\"children\":[\"$\",\"body\",null,{\"className\":\"bg-surface text-text font-sans antialiased\",\"children\":[\"$\",\"div\",null,{\"className\":\"flex h-screen overflow-hidden\",\"children\":[[\"$\",\"$L2\",null,{}],[\"$\",\"main\",null,{\"className\":\"flex-1 overflow-y-auto bg-grid\",\"children\":[\"$\",\"$L3\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L4\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":[[[\"$\",\"title\",null,{\"children\":\"404: This page could not be found.\"}],[\"$\",\"div\",null,{\"style\":{\"fontFamily\":\"system-ui,\\\"Segoe UI\\\",Roboto,Helvetica,Arial,sans-serif,\\\"Apple Color Emoji\\\",\\\"Segoe UI Emoji\\\"\",\"height\":\"100vh\",\"textAlign\":\"center\",\"display\":\"flex\",\"flexDirection\":\"column\",\"alignItems\":\"center\",\"justifyContent\":\"center\"},\"children\":[\"$\",\"div\",null,{\"children\":[[\"$\",\"style\",null,{\"dangerouslySetInnerHTML\":{\"__html\":\"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}\"}}],[\"$\",\"h1\",null,{\"className\":\"next-error-h1\",\"style\":{\"display\":\"inline-block\",\"margin\":\"0 20px 0 0\",\"padding\":\"0 23px 0 0\",\"fontSize\":24,\"fontWeight\":500,\"verticalAlign\":\"top\",\"lineHeight\":\"49px\"},\"children\":404}],[\"$\",\"div\",null,{\"style\":{\"display\":\"inline-block\"},\"children\":[\"$\",\"h2\",null,{\"style\":{\"fontSize\":14,\"fontWeight\":400,\"lineHeight\":\"49px\",\"margin\":0},\"children\":\"This page could not be found.\"}]}]]}]}]],[]],\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]}]]}]}]}]]}],{\"children\":[[\"$\",\"$1\",\"c\",{\"children\":[null,[\"$\",\"$L3\",null,{\"parallelRouterKey\":\"children\",\"error\":\"$undefined\",\"errorStyles\":\"$undefined\",\"errorScripts\":\"$undefined\",\"template\":[\"$\",\"$L4\",null,{}],\"templateStyles\":\"$undefined\",\"templateScripts\":\"$undefined\",\"notFound\":\"$undefined\",\"forbidden\":\"$undefined\",\"unauthorized\":\"$undefined\"}]]}],{\"children\":[[\"$\",\"$1\",\"c\",{\"children\":[\"$L5\",[[\"$\",\"script\",\"script-0\",{\"src\":\"/_next/static/chunks/12p3iqtw2ohfq.js\",\"async\":true,\"nonce\":\"$undefined\"}]],[\"$\",\"$L6\",null,{\"children\":[\"$\",\"$7\",null,{\"name\":\"Next.MetadataOutlet\",\"children\":\"$@8\"}]}]]}],{},null,false,null]},null,false,\"$@9\"]},null,false,null],[\"$\",\"$1\",\"h\",{\"children\":[null,[\"$\",\"$La\",null,{\"children\":\"$Lb\"}],[\"$\",\"div\",null,{\"hidden\":true,\"children\":[\"$\",\"$Lc\",null,{\"children\":[\"$\",\"$7\",null,{\"name\":\"Next.Metadata\",\"children\":\"$Ld\"}]}]}],[\"$\",\"meta\",null,{\"name\":\"next-size-adjust\",\"content\":\"\"}]]}],false]],\"m\":\"$undefined\",\"G\":[\"$e\",[[\"$\",\"link\",\"0\",{\"rel\":\"stylesheet\",\"href\":\"/_next/static/chunks/0iym2_f33sxs7.css\",\"precedence\":\"next\",\"crossOrigin\":\"$undefined\",\"nonce\":\"$undefined\"}]]],\"S\":true,\"h\":null,\"s\":\"$undefined\",\"l\":\"$undefined\",\"p\":\"$undefined\",\"d\":\"$undefined\",\"b\":\"BgLP6ChyOyE0k8Ahr8F2H\"}\n"])</script><script>self.__next_f.push([1,"f:[]\n9:\"$Wf\"\n"])</script><script>self.__next_f.push([1,"b:[[\"$\",\"meta\",\"0\",{\"charSet\":\"utf-8\"}],[\"$\",\"meta\",\"1\",{\"name\":\"viewport\",\"content\":\"width=device-width, initial-scale=1\"}]]\n"])</script><script>self.__next_f.push([1,"10:I[27201,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\"],\"IconMark\"]\n8:null\nd:[[\"$\",\"title\",\"0\",{\"children\":\"MiClaw\"}],[\"$\",\"meta\",\"1\",{\"name\":\"description\",\"content\":\"Claude Code configuration visualizer\"}],[\"$\",\"link\",\"2\",{\"rel\":\"icon\",\"href\":\"/favicon.ico?favicon.0x3dzn~oxb6tn.ico\",\"sizes\":\"256x256\",\"type\":\"image/x-icon\"}],[\"$\",\"$L10\",\"3\",{}]]\n"])</script><script>self.__next_f.push([1,"11:I[22450,[\"/_next/static/chunks/0mmpyn9fv2fjf.js\",\"/_next/static/chunks/0d3shmwh5_nmn.js\",\"/_next/static/chunks/12p3iqtw2ohfq.js\"],\"ExpandableBody\"]\n12:T133b,"])</script><script>self.__next_f.push([1,"# RULES\n\n- Always use concise explanation\n- Main languages are Python and TypeScript\n- Never use emojis when writing code or markdown\n- NEVER use non-standard symbols like \"✓|✗|☐|○\" when writing code or markdown\n- Use parametrized tests whenever possible\n- Listed below are a handful of different 'Workflow' guides. Adhere to them as best as possible\n- 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.\n\n## REPOS\n\nBefore working in any repo, read its instruction file:\n\n| Repo | Path | Instructions |\n|------|------|--------------|\n| platform-services | ~/Desktop/platform-services | AGENTS.md |\n| infrastructure | ~/Desktop/infrastructure | CLAUDE.md |\n| web-app | ~/Desktop/web-app | .clauderules |\n\nWhen spawning subagents for a specific repo, include the instruction file path in the prompt.\n\n## Code Quality Standards\n\nCode must be clean, readable, and maintainable. Hold yourself to extremely high standards:\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Parametrized tests**: Combine similar test cases with different inputs into `@pytest.mark.parametrize` instead of copy-pasting test methods.\n- **Extract repeated patterns**: If the same mock setup or helper logic appears 3+ times, extract it to a fixture or helper function.\n\n## Git Restrictions\n\nAgents must NEVER run `git add` or `git commit` commands. The user will handle all git staging and commits manually.\n\n## PR Review Workflow (ps-copy)\n\nThere is a second copy of platform-services at `~/Desktop/ps-copy/platform-services` used for reviewing PRs.\n\nWhen asked to \"Review PR \u003cnumber\u003e in ps-copy\":\n1. Navigate to `~/Desktop/ps-copy/platform-services`\n2. Checkout main branch: `git checkout main`\n3. Run `git fetch \u0026\u0026 git pull`\n4. Read in the repositories developmnet guide AGENTS.md file (FAIL IF YOU CANNOT FIND IT)\n5. Run the `/review` task for the specified PR\n6. DO NOT post an actual comment on the review. Just review locally.\n\n## Linear Ticket Workflow\n\n- Ticket titles must be under 50 characters. Linear auto-generates branch names from titles, so short titles produce clean branch names.\n- 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.\n\n## Cross-Repo Workflow\n\nWhen working across multiple repos in a single task:\n1. Read all relevant instruction files first\n2. Follow each repo's conventions when modifying its code\n3. Coordinate changes that span repos (e.g., API changes in platform-services affecting web-app)\n\n## Querying Logs in Axiom Workflow\n\nQuerying Logs in Axiom\n\nLogs 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**.\n\n### Key Fields\n\n| Field | Description |\n| ------- | ------------- |\n| `_time` | Timestamp |\n| `logGroup` | CloudWatch log group (e.g., `/aws/lambda/account-service`) |\n| `message` | Log message |\n| `levelname` | Log level (`INFO`, `ERROR`, etc.) |\n| `service` | Service name |\n| `correlationId` | UUID for tracing requests across services |\n| `accountId`, `userId`, `patientId` | Entity identifiers |\n| `path`, `method`, `statusCode`, `took` | HTTP request details |\n| `errorMessage`, `errorType` | Error details |\n| `data` | Object containing extra fields not in the standard set |\n\n### Example Queries\n\n```apl\n// Errors in a service\n['bioscope-dev']\n| where levelname == \"ERROR\" and logGroup == \"/aws/lambda/account-service\"\n\n// Trace a request across services\n['bioscope-dev']\n| where correlationId == \"550e8400-e29b-41d4-a716-446655440000\"\n| order by _time asc\n\n// Slow requests\n['bioscope-dev']\n| where took \u003e 1000\n| project _time, service, path, took\n\n// Error counts by service (last hour)\n['bioscope-dev']\n| where _time \u003e ago(1h) and levelname == \"ERROR\"\n| summarize count() by logGroup"])</script><script>self.__next_f.push([1,"5:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$12\",\"previewLines\":8}]]}]]}]]}],\"$L13\",\"$L14\",\"$L15\",\"$L16\",\"$L17\"],false]}]\n"])</script><script>self.__next_f.push([1,"18:Tcb1,"])</script><script>self.__next_f.push([1,"# Bioscope Bioinformatics 2026 Roadmap\n\n## Project Overview\nInteractive roadmap visualization tool for Bioscope Bioinformatics' 2026 strategic planning. Single-page web app with a Node.js backend for data persistence.\n\n## Files\n\n| File | Purpose |\n|------|---------|\n| `roadmap.html` | Main application - all HTML, CSS, and JavaScript in one file |\n| `roadmap-data.json` | Data storage - umbrellas, projects, subtasks, timelines |\n| `server.js` | Node.js server (port 3000) - serves HTML and handles JSON read/write |\n\n## How to Run\n```bash\ncd /Users/gabry/Desktop/ROADMAP_2026\nnode server.js\n# Open http://localhost:3000\n```\n\n## Data Model\n\n```json\n{\n  \"umbrellas\": [\n    {\n      \"id\": \"wgs\",\n      \"title\": \"WGS (Whole Genome Sequencing)\",\n      \"icon\": \"🧬\",\n      \"projects\": [\n        {\n          \"id\": 1,\n          \"title\": \"Project Name\",\n          \"monthStart\": 0,      // 0-11 (Jan-Dec), null = TBD\n          \"monthEnd\": 2,        // 0-11 (Jan-Dec), null = TBD\n          \"subtasks\": [\n            { \"id\": 101, \"text\": \"Task description\", \"note\": \"Optional note\" }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n### Umbrella Categories\n- `wgs` - WGS (Whole Genome Sequencing) 🧬\n- `microbiome` - Microbiome 🦠\n- `omics` - Other Omics \u0026 Tooling 🔬\n\n## Key Features Implemented\n\n### Two Views\n1. **Projects View** - Expandable umbrella tiles with two-column layout (projects list | tasks panel)\n2. **Timeline View** - Gantt-style visualization across 12 months with Q1-Q4 labels\n\n### Timeline Interactions\n- **Drag rows** to reorder projects within an umbrella\n- **Drag rows between umbrellas** to move projects to different categories\n- **Drag timeline bars** left/right to move project timing\n- **Drag bar edges** (resize handles) to expand/shrink duration\n- **Tooltip** shows month range while dragging (e.g., \"April - September\")\n- **TBD projects** shown as dashed badge - click to set timeline\n\n### Edit Functionality\n- Edit button on each project (both views)\n- Modal with title and month range (January-December dropdowns)\n- Delete project option\n\n### Data Persistence\n- **Save button** - POST to `/api/data` writes to `roadmap-data.json`\n- **Export button** - Downloads JSON file\n- LocalStorage used for UI state (expanded umbrellas, selected projects)\n\n## Technical Notes\n\n### Month-Based Timeline\nChanged from quarter-based (Q1-Q4) to month-based (0-11) for finer control:\n- `monthStart: 0` = January\n- `monthEnd: 11` = December\n- `null` values = TBD (unscheduled)\n\n### CSS Variables (theming)\n```css\n--wgs-color: #3b82f6      /* Blue */\n--microbiome-color: #10b981  /* Green */\n--omics-color: #8b5cf6    /* Purple */\n```\n\n### Key JavaScript Functions\n- `renderProjectsView()` - Renders umbrella tiles\n- `renderTimeline()` - Renders Gantt chart\n- `initTimelineDragDrop()` - Row drag/drop between umbrellas\n- `initBarDragResize()` - Timeline bar drag/resize\n- `saveToServer()` - POST data to server\n- `loadFromServer()` - GET data from server\n\n## Potential Future Enhancements\n- Progress tracking (checkboxes were removed but could be re-added)\n- Dependencies between projects (arrows/lines)\n- Multiple years view\n- Team/owner assignment\n- Color customization per project\n- Export to PDF/image\n- Milestones/markers on timeline"])</script><script>self.__next_f.push([1,"13:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$18\",\"previewLines\":8}]]}]]}]]}]\n19:Tfec,"])</script><script>self.__next_f.push([1,"# Repository Standards\n\n## CRITICAL SAFETY RULES\n\n**NEVER RUN APPLIES**\nClaude can ONLY run the following commands. All apply operations must be performed by humans.\n\n```bash\n# Allowed\ntofu validate\ntofu fmt\ntofu fmt -check -diff -recursive\ntofu init\n\n# NEVER run\ntofu apply\ntofu destroy\n```\n\nFor the commands that are allowed, you can and should `cd` into the appropriate stack or module directory and run the command.\n\n## Repository Structure\n\n- `stacks/` - Environment-specific configurations with separate state management\n- `modules/` - Reusable OpenTofu modules (some modules may also call other modules)\n\n## Code Standards\n\n### Main Files\n\nAll resources must be in modules, never in a main.tf under the `stacks/` directory. The main.tf should only call other modules.\n\n### Module Standards\n\n- Each resource type goes in an appropriately named *.tf file (IAM resources in iam.tf, etc.)\n- 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.\n- Every module must include a README.md that provides an overview of what the module provisions and any gotchas\n- 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\n\n### General Conventions\n\n- Use consistent naming: `{service_name}_{resource_type}`\n- Never hardcode secrets or credentials\n\n## Web Search\n\nSince 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.\n\n## GitHub Actions\n\nAll 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.\n\n```yaml\n# Good\n- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4\n\n# Bad\n- uses: actions/checkout@v4\n```\n\nInternal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.\n\n## Pull Request Guidelines\n\n### Cross-Repo Dependency Ordering\n\n`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:\n\n- 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.\n- 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.\n\n### Code Standards in Reviews\n\nWhen 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."])</script><script>self.__next_f.push([1,"14:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$19\",\"previewLines\":8}]]}],\"$L1a\"]}]]}]\n1b:T838e,"])</script><script>self.__next_f.push([1,"# Platform Services Development Guide\n\nThis 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.\n\n## Project Structure\n\nThis is a monorepo containing multiple Python packages that follow consistent patterns and conventions.\n\n## Account Types\n\nThere are two account types, stored as `account_type` in the `accounts` DynamoDB table:\n\n- **`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.\n- **`practice`** — A practice with one or more physicians and potentially many patients. Has two billing models:\n  - **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.\n  - **Standard** — physician self-signs up, billing is per-patient via yearly subscriptions tracked in the `patient-entitlements` table.\n\nFor 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).\n\n## GitHub Actions\n\nAll 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.\n\n```yaml\n# Good\n- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4\n\n# Bad\n- uses: actions/checkout@v4\n```\n\nInternal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.\n\n## Dockerfile Dependency Installation\n\nAll 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.\n\n### Standard pattern (uv-based images)\n\nFor Dockerfiles that use uv and target the project's Python version:\n\n```dockerfile\n# Export lockfile-pinned dependencies and install without resolution\nRUN uv export --frozen --no-dev --no-editable --package \u003cpackage-name\u003e -o /tmp/requirements.txt \u0026\u0026 \\\n    uv pip install --system --no-deps -r /tmp/requirements.txt\n```\n\nThis 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.\n\n### Non-uv base images (e.g., mriqc, fastsurfer)\n\nFor 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:\n\n```dockerfile\nFROM \u003cbase-image\u003e\nUSER root\nWORKDIR /app\n\nRUN pip install --no-cache-dir \"uv\u003e=0.10.0,\u003c0.11.0\"\n\nCOPY pyproject.toml uv.lock ./\nCOPY packages/\u003cworkspace-deps\u003e/ ./packages/\u003cworkspace-deps\u003e/\n\n# Install Python under /app so non-root users can access it\nARG PYTHON_VERSION\nENV UV_PYTHON_INSTALL_DIR=/app/.python\nRUN uv sync --frozen --no-dev --python ${PYTHON_VERSION} --package \u003cpackage-name\u003e\n\nENTRYPOINT [\"/app/.venv/bin/python\", \"-m\", \"\u003cpackage_module\u003e.main\"]\n```\n\n### Non-workspace dependencies\n\nAny `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 \u003cpackage\u003e` is not allowed.\n\n## Pull Request Guidelines\n\n### Cross-Repo Dependency Ordering\n\n`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:\n\nIf 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.\n\n### Dependency Pinning\n\nAll external package dependencies must use the compatible release operator (`~=`). Do not use `\u003e=` as it leaves the version unbounded. Exact pins (`==`) are acceptable when a package requires a specific version.\n\n### Code Standards\n\nWhen 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.\n\nIt 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.\n\nFor 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.\n\n### IDOR Prevention\n\nWhen reviewing route handlers, watch for authorization gaps that could allow users to access or modify resources belonging to other accounts/patients:\n\n- **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.\n- **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.\n- **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`.\n- **List/query endpoints**: Queries that return collections must scope by `account_id` (or `patient_id` where applicable) to prevent cross-account data leakage.\n- **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.\n\n### Billing Enforcement\n\nAny 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`:\n\n- **`ensure_patient_billing_access_from_path`**: Use when `patient_id` is a path parameter. Add as a `Depends()` dependency on the route.\n- **`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.\n\nBoth 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.\n\n## Commands\n\nNx commands are run with:\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:\u003ccommand\u003e\n```\n\nFor example, to run tests for the `dynamodb-helper` package:\n\n```bash\npnpm exec nx run dynamodb-helper:test\n```\n\nAvailable commands are defined in `nx.json` at the root and in each package's `project.json` file.\n\n### Formatting, Linting, and Type Checking\n\nFor 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:\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:format\npnpm exec nx run \u003cpackage-name\u003e:lint\npnpm exec nx run \u003cpackage-name\u003e:type-check\n```\n\n**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.\n\n## Types\n\nThis repo makes heavy use of Pydantic V2 models. Shared models are typically defined in the `bioscope-types` package.\n\nWe have a `BioscopeBaseModel` class that is a subclass of `BaseModel` that adds some additional functionality, mostly adding camelCase aliases to the fields.\nIn our code, we use snake_case for everything, but anything leaving or entering Python should be camelCase, for example:\n\n- Network requests and responses\n- Database rows\n- Logging statements\n\nThe shared `BioscopeBaseModel` automatically takes care of this for us.\n\n## FastAPI Routes (`packages/**/src/**/routes/**.py`)\n\n### Basic Conventions\n\n- Route functions should be async\n- Router should have a common prefix per file\n- Follow standard REST conventions\n\n### Headers and Authentication\n\nThese routes are configured with an AWS API Gateway. Most routes are secured with a custom lambda authorizer.\n\nThis authorizer validates the Bearer JWT token and extracts the user ID from the token.\nRequests come in with a `Bioscope-Account-Id` header that contains the account ID.\nThe authorizer ensures that the user in the JWT belongs to the account.\nThis means that these headers are \"safe\" and guaranteed to be valid for the calling user.\n\nTherefore, authorization (i.e. to prevent IDOR, etc.) should be done via these headers.\n\nThese headers can be injected into the route function as dependencies using the `BioscopeUserIdHeaderDeps` and `BioscopeAccountIdHeaderDeps` classes.\n\n### Models\n\nRequest and response models should both be Pydantic models that inherit `BioscopeBaseModel`.\n`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.\n\n### Logging\n\nRoutes should use the `BioscopeLoggerDeps` class to inject the logger into the route function.\nThis logger is automatically configured to include the user ID and account ID in the log messages.\n\n#### PII/PHI Logging Rules\n\n**Fields that must NEVER be logged:**\n\n- Patient names, emails, phone numbers, addresses, dates of birth\n- Medical data (diagnoses, medications, lab results, clinical notes)\n- Full request/response bodies from external APIs (FHIR, EHR, lab vendors, etc.)\n- Webhook payloads (these often contain patient data or credentials)\n- Secrets, tokens, API keys, credentials — omit these entirely (no length hints either)\n- Template parameters that contain patient-facing content (e.g., SMS/email body text)\n\n**Safe fields that CAN be logged:**\n\n- Internal UUIDs: `patient_id`, `account_id`, `user_id`, `order_id`, `connection_id`, `correlation_id`\n- Status codes, HTTP methods, URL paths\n- Counts and lengths (e.g., number of records processed, response body length)\n- Template/event names, enum values, operation names\n- Durations, timestamps, retry counts\n\n**Redaction pattern** — when context about a sensitive value is needed for debugging, log a length hint instead of the value:\n\n```python\n# Good — log a length hint for debugging without exposing the value\nlogger.info(\"received webhook\", extra={\"bodyLength\": len(body)})\n\n# Good — log only safe identifiers\nlogger.info(\"processing patient\", extra={\"patientId\": patient_id, \"accountId\": account_id})\n\n# Bad — logs the entire webhook/response body (may contain PII/PHI)\nlogger.info(\"received webhook\", extra={\"body\": body})\nlogger.info(\"API response\", extra={\"response\": response.json()})\n```\n\n**Never log full request/response bodies** — log the status code and body length instead:\n\n```python\n# Good\nlogger.info(\"FHIR response\", extra={\"statusCode\": response.status_code, \"bodyLength\": len(response.content)})\n\n# Bad\nlogger.info(\"FHIR response\", extra={\"body\": response.json()})\n```\n\n**Exception messages** — do not embed API response text in exception messages, as these end up in logs via `logger.exception`:\n\n```python\n# Good\nraise ValueError(f\"EHR API returned {response.status_code}\")\n\n# Bad — response body may contain PHI\nraise ValueError(f\"EHR API error: {response.text}\")\n```\n\n#### Formatting\n\nDo 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).\n\n```python\n# Good\nextra={\"metric\": usage_metric.model_dump()}\n\n# Bad\nextra={\"metric\": usage_metric.model_dump_json()}\nextra={\"metric\": json.dumps(usage_metric.model_dump())}\n```\n\n### HTTP Client\n\n`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`.\n\nWhen testing code that uses `httpx`, use `respx` for mocking. Use the **pytest fixture pattern for this**.\n\n### Relative Versus Absolute Imports\n\nProduction code should always use absolute imports. For example:\n\n```python\nfrom account_service.models import Account  # GOOD\nfrom .models import Account  # BAD\n```\n\nHowever, 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:\n\n```python\nfrom .conftest import build_data  # GOOD\nfrom tests.conftest import build_data  # BAD\n```\n\n### Error Handling\n\nRaise `HTTPException` with appropriate status code and detail message\n\n## Lambda Handlers (`packages/**/handler.py`)\n\n### Handler Types\n\n1. **LambdaHandler** - base handler for non-API Gateway functions\n2. **HttpHandler** - extends LambdaHandler with API Gateway support (requires `lambda-handler[api]`)\n\n### Lazy Loading Pattern\n\nMany 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.\n\n**Solution**: Use lazy loading in `handler.py` files only. Load direct invocation handling code only when needed, and vice versa for API Gateway routes.\n\n**Example**:\n\n```python\nfrom lambda_handler.http_handler import HttpHandler\n\ndef get_app():\n    from my_service.app import app  # noqa: PLC0415\n    return app\n\nhandler = HttpHandler(get_app)\n\n@handler.direct_invocation()\ndef handle_direct_invocation(event: DirectInvocationEvent, logger: BioscopeLogger):\n    from my_service.handlers.handler_one import handle_handler_one  # noqa: PLC0415\n    return handle_handler_one(event, logger)\n```\n\n**Important**:\n\n- Restrict lazy imports to `handler.py` only\n- Keep common imports (logger, types, handler framework) at module level\n- Use `# noqa: PLC0415` to suppress linting warnings\n- Never lazy load in business logic or service modules\n\n### Decorators\n\n| Event Source      | Decorator                    | Required kwarg         | Notes                                    |\n| ----------------- | ---------------------------- | ---------------------- | ---------------------------------------- |\n| SQS               | `@handler.sqs`               | `queue_name=\"\u003cqueue\u003e\"` |                                          |\n| SNS               | `@handler.sns`               | `topic_name=\"\u003ctopic\u003e\"` |                                          |\n| Direct Invocation | `@handler.direct_invocation` | N/A                    | Operation extracted from request model   |\n| Event Bridge      | `@handler.event_bridge`      | N/A                    | Handles all EventBridge events           |\n| API Gateway Auth  | `@handler.authorizer`        | N/A                    | For custom API Gateway authorizers       |\n| Health Check      | `@handler.health_check`      | N/A                    | Custom health check (built-in available) |\n\n**Notes**:\n\n- EventBridge and authorizer handlers do not use operation discriminators - they handle all events of their type sent to the function.\n- Direct invocation handlers automatically extract the `operation` from the request model's `operation` class attribute.\n- A built-in health check handler is automatically registered for all Lambda functions and responds to `{\"operation\": \"healthCheck\"}` requests.\n\n### Message Payloads\n\n• Define a Pydantic model that **inherits `BioscopeBaseModel`** for every distinct message body.\n• Models should be defined in the `bioscope_types` package under the `services` module.\n\nAlways annotate the first parameter with the corresponding event model from `lambda_handler.models`, e.g. `SqsEvent[MyMessage]`.\n`MyMessage` should be a new Pydantic model that inherits `BioscopeBaseModel`.\n`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.\n\n### Dependency Injection\n\nHandler functions may declare these optional parameters which will be injected automatically:\n\n- `logger: BioscopeLogger` - the project-wide structured logger.\n- `context: LambdaContext` - the AWS Lambda context object.\n\n### Example (SQS)\n\n```python\nfrom lambda_handler.handler import LambdaHandler\nfrom lambda_handler.models.sqs import SqsEvent\nfrom bioscope_types.common import BioscopeBaseModel\n\nhandler = LambdaHandler()\n\nclass MySqsMessage(BioscopeBaseModel):\n    my_custom_field: str\n\n@handler.sqs(queue_name=\"my-queue\")\ndef handle_sqs_event(event: SqsEvent[MySqsMessage], logger, context):\n    logger.info(\"processing message\", extra={\"myCustomField\": event.body.my_custom_field})\n```\n\n### Style Rules\n\n- Use **explicit type annotations** everywhere.\n- Keep handler bodies minimal; delegate business logic to service modules.\n- Use the provided `logger`, not `print`, for output.\n- 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.\n\n### Handler Organization (`packages/**/src/**/handlers/**/*.py`)\n\nFor services with many direct invocation handlers, organize them in a dedicated `handlers` directory rather than implementing the business logic directly in `handler.py`.\n\n### Structure\n\n```text\nsrc/\n  service_name/\n    handler.py          # Contains @handler.direct_invocation decorators\n    handlers/\n      __init__.py       # Exports all handler functions\n      handler_one.py    # Individual handler implementation\n      handler_two.py    # Individual handler implementation\n```\n\n### Handler Function Signature\n\nHandler functions should follow this standardized signature:\n\n```python\nasync def handle_operation_name(\n    args: OperationArgs,\n    logger: BioscopeLogger,\n) -\u003e OperationResponse:\n    # Implementation here\n```\n\nWhere:\n\n- `args` is the operation's arguments model from `bioscope_types.services`\n- `logger` is the structured logger instance\n- Return type matches the operation's response model\n\n### Main Handler File\n\nThe main `handler.py` file should delegate to the individual handlers:\n\n```python\nfrom service_name.handlers import handle_operation_name\n\n@handler.direct_invocation()\nasync def operation_name_handler(\n    event: OperationRequest, parent_logger: BioscopeLogger\n) -\u003e OperationResponse:\n    return await handle_operation_name(\n        args=event.args,\n        logger=parent_logger.child(\n            {\n                # Add relevant fields from event.args (in camelCase and avoiding PHI/PII)\n            }\n        ),\n    )\n```\n\n## AWS Services (`packages/**/src/**/aws.py`)\n\n**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`).\n\n### AWS Abstraction Pattern\n\nCreate `src/package_name/aws.py`:\n\n```python\nfrom contextlib import asynccontextmanager\nfrom aioboto3 import Session\n\nsession = Session()\n\n@asynccontextmanager\nasync def get_service_name():\n    async with session.client(\"service-name\") as client:\n        yield client\n```\n\n### Usage in Production Code\n\n```python\nfrom package_name.aws import get_service_name\n\nasync def some_operation() -\u003e None:\n    async with get_service_name() as client:\n        await client.some_api_call()\n```\n\n## Testing (`packages/**/tests/**/*.py`)\n\n### Basic Rules\n\n- Prefer **pytest** for all unit tests.\n- 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.\n- Tests are all run with `asyncio_mode = \"auto\"` in `pyproject.toml`, so tests don't need to be marked as async individually.\n- **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)\n- Use pytest fixtures for both mocking and for defining common test data.\n- 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.\n- 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.\n\n### Test Structure\n\n- Mirror source code structure in test organization\n- Individual classes for each function being tested\n- Individual methods for each test case\n\nExample:\n\n```python\nclass TestCopyS3ToTemp:\n    def test_happy_path(self):\n        pass\n\n    def test_invalid_url_format(self):\n        pass\n\n    def test_s3_error(self):\n        pass\n```\n\n### Assertions\n\nWhen performing assertions on data, compare the entire object as much as possible rather than individual assertions for each field.\n\nFor example, instead of:\n\n```python\nassert result is not None\nassert len(result) == 1\nassert result[0].id == \"123\"\nassert result[0].name == \"John Doe\"\nassert result[0].email == \"john.doe@example.com\"\n```\n\nyou should do:\n\n```python\nassert result == [User(\n    id=\"123\",\n    name=\"John Doe\",\n    email=\"john.doe@example.com\"\n)]\n```\n\nWhen 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.\nFor example, instead of:\n\n```python\nassert mock_foo.call_args.args == (\"123\", \"John Doe\", \"john.doe@example.com\")\n```\n\nyou should do:\n\n```python\nmock_foo.assert_called_once_with(\"123\", \"John Doe\", \"john.doe@example.com\")\n```\n\n### Async vs Sync Assertions\n\n**IMPORTANT**: For async functions (using `AsyncMock`), use `assert_awaited...` methods:\n\n- `assert_awaited_once()` instead of `assert_called_once()`\n- `assert_awaited_once_with(args)` instead of `assert_called_once_with(args)`\n- `assert_not_awaited()` instead of `assert_not_called()`\n\nFor sync functions (using `MagicMock`), use `assert_called...` methods:\n\n- `assert_called_once()`\n- `assert_called_once_with(args)`\n- `assert_not_called()`\n\n### Positive and Negative Assertions\n\nAlways include both positive assertions (what should happen) and negative assertions (what should NOT happen) to ensure functions aren't being called unexpectedly.\n\n### Mocking\n\nAs 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.\n\nMocks 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.\n\n#### Mock Fixture Naming\n\nMock fixtures should be named `mock_\u003cfunction_name\u003e`, matching the function being patched. For example:\n\n```python\n# Patching ensure_account_has_stripe_customer_id\n@pytest.fixture\ndef mock_ensure_account_has_stripe_customer_id(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"some_service.module.ensure_account_has_stripe_customer_id\")\n\n# Patching invoke_lambda\n@pytest.fixture\ndef mock_invoke_lambda(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"lambda_client.client.invoke_lambda\")\n```\n\n**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_\u003cmodule_name\u003e_\u003cfunction_name\u003e`.\n\n```python\n# Two different get_by_id functions — module prefix disambiguates\n@pytest.fixture\ndef mock_accounts_get_by_id(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"dynamodb_helper.models.accounts.get_by_id\")\n\n@pytest.fixture\ndef mock_patients_get_by_id(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"dynamodb_helper.models.patients.get_by_id\")\n```\n\n#### Mock Fixture Placement\n\nMock 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`.\n\n#### AWS Service Mocking\n\nWhen testing code that uses AWS services, follow this pattern (see [AWS Services](#aws-services-packagessrcawspy) section for the production abstraction):\n\n**Create AWS abstraction** (`src/package_name/aws.py`):\n\n```python\nfrom contextlib import asynccontextmanager\nfrom aioboto3 import Session\n\nsession = Session()\n\n@asynccontextmanager\nasync def get_s3():\n    async with session.client(\"s3\") as s3_client:\n        yield s3_client\n```\n\n**Use abstraction in production code**:\n\n```python\nfrom package_name.aws import get_s3\n\nasync def upload_file(bucket: str, key: str, content: bytes) -\u003e None:\n    async with get_s3() as s3:\n        await s3.put_object(Bucket=bucket, Key=key, Body=content)\n```\n\n**Test with botocore stubber**:\n\n```python\nfrom collections.abc import AsyncGenerator\nfrom contextlib import asynccontextmanager\nimport pytest\nfrom aioboto3 import Session\nfrom botocore.stub import Stubber\nfrom pytest_mock import MockerFixture, MockType\n\n@pytest.fixture(autouse=True)\ndef fake_aws_env(monkeypatch: pytest.MonkeyPatch) -\u003e None:\n    monkeypatch.setenv(\"AWS_ACCESS_KEY_ID\", \"testing\")\n    monkeypatch.setenv(\"AWS_SECRET_ACCESS_KEY\", \"testing\")\n    monkeypatch.setenv(\"AWS_SESSION_TOKEN\", \"testing\")\n    monkeypatch.setenv(\"AWS_DEFAULT_REGION\", \"us-east-2\")\n\n@pytest.fixture\ndef mock_get_s3(mocker: MockerFixture) -\u003e MockType:\n    return mocker.patch(\"package_name.client.get_s3\")\n\n@pytest.fixture\nasync def s3_stub(mock_get_s3: MockType) -\u003e AsyncGenerator[Stubber]:\n    session = Session()\n    async with session.client(\"s3\", region_name=\"us-east-2\") as s3_client:\n        stubber = Stubber(s3_client)\n        stubber.activate()\n\n        @asynccontextmanager\n        async def _fake_get_s3():\n            yield s3_client\n\n        mock_get_s3.side_effect = _fake_get_s3\n        yield stubber\n        stubber.assert_no_pending_responses()\n        stubber.deactivate()\n\nclass TestUploadFile:\n    async def test_upload_success(self, s3_stub: Stubber):\n        s3_stub.add_response(\n            \"put_object\",\n            {},\n            {\n                \"Bucket\": \"test-bucket\",\n                \"Key\": \"test-key\",\n                \"Body\": b\"test-content\",\n            },\n        )\n\n        await upload_file(\"test-bucket\", \"test-key\", b\"test-content\")\n```\n\nThis `aws.py` file itself should be added to the `omit` list in the `pyproject.toml` file of the package. For example:\n\n```toml\nomit = [\n    \"src/\u003cpackage_name\u003e/aws.py\",\n]\n```\n\n### Running Tests\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:test\n```\n\n### Fixtures\n\n#### Logger Fixture\n\n**IMPORTANT**: Always use a real `BioscopeLogger` instance in tests, not a mock. Create a `conftest.py` file in your package's test directory:\n\n```python\nimport pytest\nfrom bioscope_logger import BioscopeLogger, get_logger\nfrom uuid import uuid4\n\n@pytest.fixture\ndef logger() -\u003e BioscopeLogger:\n    return get_logger(\"package-name\", uuid4())\n```\n\nThis 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.\n\n#### Other Fixtures\n\nExample:\n\n```python\nfrom unittest.mock import AsyncMock, MagicMock\nfrom pytest_mock import MockerFixture\nfrom models import Patient\n\n@pytest.fixture\ndef patient() -\u003e Patient:\n    return Patient(\n        id=\"123\",\n        name=\"John Doe\",\n    )\n\n@pytest.fixture\ndef mock_get_patient(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"some_service.utils.get_patient\")\n\n@pytest.fixture\ndef mock_sync_function(mocker: MockerFixture) -\u003e MagicMock:\n    return mocker.patch(\"some_service.utils.sync_function\")\n\nclass TestMyFunction:\n    async def test_happy_path(self, patient: Patient, mock_get_patient: AsyncMock):\n        mock_get_patient.return_value = patient\n        # Use assert_awaited_once_with for async mocks\n        mock_get_patient.assert_awaited_once_with(\"patient_id\")\n\n    def test_sync_function(self, mock_sync_function: MagicMock):\n        mock_sync_function.return_value = \"result\"\n        # Use assert_called_once_with for sync mocks\n        mock_sync_function.assert_called_once_with(\"arg\")\n```\n\n**Fixture Type Guidelines**:\n\n- Use `MagicMock` for synchronous functions\n- Use `AsyncMock` for asynchronous functions\n- pytest-mock automatically creates the correct mock type, but explicit typing helps with IDE support\n\n### Test Coverage\n\nAlways aim for 100% coverage. `#pragma: no cover` can be used to exclude specific lines from coverage.\n\n### Do NOT create `__init__.py` files in test directories\n\nYou should NEVER create an `__init__.py` file in a test directory. Doing so will break the VSCode/Cursor test explorer.\n\n## Querying Logs in Axiom\n\nUse 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.\n\nLogs 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**.\n\n### Key Fields\n\n| Field                                  | Description                                                |\n| -------------------------------------- | ---------------------------------------------------------- |\n| `_time`                                | Timestamp                                                  |\n| `logGroup`                             | CloudWatch log group (e.g., `/aws/lambda/account-service`) |\n| `message`                              | Log message                                                |\n| `levelname`                            | Log level (`INFO`, `ERROR`, etc.)                          |\n| `service`                              | Service name                                               |\n| `correlationId`                        | UUID for tracing requests across services                  |\n| `accountId`, `userId`, `patientId`     | Entity identifiers                                         |\n| `path`, `method`, `statusCode`, `took` | HTTP request details                                       |\n| `errorMessage`, `errorType`            | Error details                                              |\n| `data`                                 | Object containing extra fields not in the standard set     |\n\n### Example Queries\n\n```apl\n// Errors in a service\n['bioscope-dev']\n| where levelname == \"ERROR\" and logGroup == \"/aws/lambda/account-service\"\n\n// Trace a request across services\n['bioscope-dev']\n| where correlationId == \"550e8400-e29b-41d4-a716-446655440000\"\n| order by _time asc\n\n// Slow requests\n['bioscope-dev']\n| where took \u003e 1000\n| project _time, service, path, took\n\n// Error counts by service (last hour)\n['bioscope-dev']\n| where _time \u003e ago(1h) and levelname == \"ERROR\"\n| summarize count() by logGroup\n```"])</script><script>self.__next_f.push([1,"15:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$1b\",\"previewLines\":8}]]}],\"$L1c\",\"$L1d\",\"$L1e\"]}]]}]\n1f:Tc8a,"])</script><script>self.__next_f.push([1,"# Web App - Claude Instructions\n\n## E2E Test Users\n\n### How test users are managed\n\nE2E 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).\n\n### How to add more test users\n\nTest 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.\n\n**Steps per user:**\n\n1. Go to https://manage.auth0.com/dashboard/us/bioscope-dev/users\n2. Click \"Create User\" (dropdown) -\u003e \"Create via UI\"\n3. Enter email: `success+test_user_N@simulator.amazonses.com`\n4. Enter password: `test123!`\n5. Click \"Create\" — this navigates to the User Details page\n6. Find the Email field (shows \"UNVERIFIED\") -\u003e click \"Edit\"\n7. In the modal, click the \"Set email as verified\" link/button -\u003e click \"Save\"\n8. Click \"Back to Users\" to return to the list\n9. Add the user to `e2e/data/users.json`\n\n**Important notes:**\n- The Auth0 dashboard is very slow. Allow 10-20 seconds between interactions.\n- \"Set email as verified\" is a clickable button/link in the Edit Email modal, not a checkbox.\n- Auth0 search indexing has a delay — newly created users may not appear in search immediately.\n- Do NOT use the app signup flow to create test users. It uses email verification codes and does not set a password.\n\n### How to test flows manually with a browser MCP server\n\nWhen using a browser MCP server (Playwright MCP, Chrome DevTools MCP, etc.) to manually test application flows against the dev environment:\n\n1. **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`).\n\n2. **Clear the test user data before testing.** This resets the user to a clean state in the backend:\n   ```bash\n   curl -X POST https://api.dev.bioscope.ai/internal/test/clear-test-users \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Bioscope-Internal-Api-Key: Ug3jsqC73u72dw41Gnzn\" \\\n     -d '{\"test_user_emails\": [\"success+test_user_N@simulator.amazonses.com\"]}'\n   ```\n\n3. **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.\n\n4. **Clear the test user data after testing.** Run the same curl command from step 2 to clean up.\n\n## GitHub Actions\n\nAll 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.\n\n```yaml\n# Good\n- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4\n\n# Bad\n- uses: actions/checkout@v4\n```\n\nInternal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.\n\n## Code Conventions\n\n- See `.claude/rules.md` for coding rules.\n- Never include PII/PHI in log metadata."])</script><script>self.__next_f.push([1,"16:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$1f\",\"previewLines\":8}]]}],\"$L20\",\"$L21\"]}]]}]\n22:T20f4,"])</script><script>self.__next_f.push([1,"# WGS Ingestion Bot\n\nSlack bot that automatically investigates WGS ingestion failures using Claude Code.\n\n## Persona\n\nYou 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.\n\n### Domain Knowledge\n\n**Pipeline scope:** Bioscope runs 30x whole genome sequencing. The analysis is limited to single nucleotide variants (SNVs) and small insertions/deletions (INDELs, \u003c1000bp). It does NOT detect or report: copy number variants (CNVs), structural variants (SVs), repeat expansions, HLA typing, or other complex variant types.\n\n**Ingestion pipeline stages (in order):**\n\n1. **Kit intake** -- GxG vendor integration, kit registration via `wgs_ingestion_service`\n2. **Raw data receipt** -- RAW_VCF, RAW_FASTQ, RAW_BAM artifacts land in S3\n3. **VCF processing** -- validation, quality filtering, invalid VCF detection (`vcf_processor`)\n4. **Iceberg partitioning** -- variant data written to Iceberg tables via Glue/Athena\n5. **WGS query** -- ClinVar + dbSNP annotation, high/low significance variant splitting (`genomics_wgs_query_service`)\n6. **Variant assessment** -- pathogenicity scoring, clinical significance classification, risk stratification, genomic tile generation (`genomics_variant_assessment_service`)\n7. **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`)\n8. **Blood typing** -- BAM subsetting, bloodAGENT phenotype prediction for ABO, RHD, and other blood group systems (`genomics_blood_type_service`)\n9. **Results delivery** -- event publishing, patient notification\n\n**Key services and their log groups:**\n\n| Service | Purpose |\n|---------|---------|\n| `wgs_ingestion_service` | Orchestrates the full pipeline via Step Functions |\n| `vcf_processor` | VCF validation and filtering |\n| `genomics_wgs_query_service` | Variant annotation with ClinVar/dbSNP, significance filtering |\n| `genomics_variant_assessment_service` | Clinical interpretation, tile generation |\n| `genomics_prs_processor` | Polygenic risk score calculation |\n| `genomics_prs_results_service` | PRS result retrieval and enrichment |\n| `genomics_blood_type_service` | Blood group phenotyping |\n| `genomics_bam_subset_processor` | BAM subsetting for blood typing |\n| `genomics_event_consumer` | WGS event processing |\n| `wgs_data_lineage_service` | Artifact traceability |\n\n\n**External databases:** ClinVar, dbSNP, ClinGen, MONDO (disease ontology), PGS Catalog\n\n**Infrastructure:** AWS -- S3 (artifacts), DynamoDB (metadata/tracking), Step Functions (orchestration), Glue (ETL), Athena (SQL over variants), Bedrock/Claude (LLM services via llm_proxy_service)\n\n### Communication Style\n\n- Be direct and technical. Lead with the finding, not the process.\n- When reporting failures, always identify: which pipeline stage failed, which service, and the relevant correlation/ingestion IDs.\n- Use standard genomics terminology without hedging (allele, zygosity, pathogenicity, etc.).\n- 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.\n- Keep Slack replies concise. Save detail for the uploaded markdown report.\n\n## Tool Restrictions\n\n- NEVER use `ide - executeCode` or any IDE tools. Use the standard `Write` tool to create report files.\n- Write all reports to `./reports/` using the `Write` tool.\n- **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.\n- **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.\n\n## Setup\n\nRequired environment variables (set in `.env`, which is gitignored):\n\n| Variable | Description |\n|----------|-------------|\n| `SLACK_APP_TOKEN` | Socket Mode app token (`xapp-...`) |\n| `SLACK_BOT_TOKEN` | Bot OAuth token (`xoxb-...`) |\n| `ALERT_CHANNEL_ID` | Slack channel ID for ingestion alerts |\n| `DM_CHANNEL_ID` | Slack channel ID for direct messaging with allowed users (optional) |\n| `PLATFORM_SERVICES_PATH` | Path to local platform-services checkout (optional, enables code cross-referencing) |\n| `INFRASTRUCTURE_PATH` | Path to local infrastructure checkout (optional, enables Terraform cross-referencing) |\n\n## Git Restrictions\n\nAgents must NEVER run `git add` or `git commit` commands. The user will handle all git staging and commits manually.\n\n## Code Quality\n\n- TypeScript (Bun runtime) for the channel plugin\n- No emojis or non-standard symbols in code or markdown\n\n## Channel Architecture\n\nAlerts flow through a Claude Code Channel plugin (`channel/server.ts`):\n\n1. Slack alert arrives via Socket Mode\n2. Channel plugin pushes it as a `notifications/claude/channel` event\n3. Claude dispatches a background Agent to run the investigation (see below)\n4. On completion, Claude uses `slack_reply` and `slack_upload_report` to post results back\n\n## Concurrent Investigations\n\nAll alerts and human messages arrive in a single conversation. To stay responsive and handle multiple events in parallel, follow these rules:\n\n### Alert handling\n\nWhen an alert arrives, ALWAYS dispatch the investigation to a **background Agent** (`run_in_background: true`). Never run investigations inline in the main conversation.\n\nThe background agent prompt MUST include:\n- The full alert text\n- The `channel_id` and `thread_ts` for Slack replies\n- Instructions to follow the `/investigate-wgs-ingestion` steps (paste or reference the full procedure)\n- 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\n\nWhen the background agent completes:\n1. Read the report it wrote to `./reports/`\n2. Upload it to the Slack thread via `slack_upload_report`\n3. Post a summary via `slack_reply`\n\n### Human message handling\n\nAlways 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.\n\n### Multiple concurrent alerts\n\nIf 2+ alerts arrive before prior investigations finish, spawn a separate background agent for each. Each agent operates independently on its own alert.\n\n## Querying Logs in Axiom\n\nLogs 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**.\n\n### Key Fields\n\n| Field | Description |\n| ------- | ------------- |\n| `_time` | Timestamp |\n| `logGroup` | CloudWatch log group (e.g., `/aws/lambda/account-service`) |\n| `message` | Log message |\n| `levelname` | Log level (`INFO`, `ERROR`, etc.) |\n| `service` | Service name |\n| `correlationId` | UUID for tracing requests across services |\n| `accountId`, `userId`, `patientId` | Entity identifiers |\n| `path`, `method`, `statusCode`, `took` | HTTP request details |\n| `errorMessage`, `errorType` | Error details |\n| `data` | Object containing extra fields not in the standard set |\n\n### Example Queries\n\n```apl\n// Errors in a service\n['bioscope-dev']\n| where levelname == \"ERROR\" and logGroup == \"/aws/lambda/account-service\"\n\n// Trace a request across services\n['bioscope-dev']\n| where correlationId == \"550e8400-e29b-41d4-a716-446655440000\"\n| order by _time asc\n\n// Slow requests\n['bioscope-dev']\n| where took \u003e 1000\n| project _time, service, path, took\n\n// Error counts by service (last hour)\n['bioscope-dev']\n| where _time \u003e ago(1h) and levelname == \"ERROR\"\n| summarize count() by logGroup\n```"])</script><script>self.__next_f.push([1,"17:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$22\",\"previewLines\":8}]]}]]}]]}]\n"])</script><script>self.__next_f.push([1,"1a:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"@AGENTS.md\",\"previewLines\":8}]]}]\n1c:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"@AGENTS.md\",\"previewLines\":8}]]}]\n23:T7d63,"])</script><script>self.__next_f.push([1,"# Platform Services Development Guide\n\nThis 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.\n\n## Project Structure\n\nThis is a monorepo containing multiple Python packages that follow consistent patterns and conventions.\n\n## Account Types\n\nThere are two account types, stored as `account_type` in the `accounts` DynamoDB table:\n\n- **`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.\n- **`practice`** — A practice with one or more physicians and potentially many patients. Has two billing models:\n  - **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.\n  - **Standard** — physician self-signs up, billing is per-patient via yearly subscriptions tracked in the `patient-entitlements` table.\n\nFor 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).\n\n## GitHub Actions\n\nAll 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.\n\n```yaml\n# Good\n- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4\n\n# Bad\n- uses: actions/checkout@v4\n```\n\nInternal `bioscope-ai/ci` actions must also be pinned to commit SHAs with `# main` as a comment.\n\n## Dockerfile Dependency Installation\n\nAll 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.\n\n### Standard pattern (uv-based images)\n\nFor Dockerfiles that use uv and target Python 3.13:\n\n```dockerfile\n# Export lockfile-pinned dependencies and install without resolution\nRUN uv export --frozen --no-dev --no-editable --package \u003cpackage-name\u003e -o /tmp/requirements.txt \u0026\u0026 \\\n    uv pip install --system --no-deps -r /tmp/requirements.txt\n```\n\nThis 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.\n\n### Non-uv base images (e.g., mriqc, fastsurfer)\n\nFor 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:\n\n```dockerfile\nFROM \u003cbase-image\u003e\nUSER root\nWORKDIR /app\n\nRUN pip install --no-cache-dir \"uv\u003e=0.10.0,\u003c0.11.0\"\n\nCOPY pyproject.toml uv.lock ./\nCOPY packages/\u003cworkspace-deps\u003e/ ./packages/\u003cworkspace-deps\u003e/\n\n# Install Python under /app so non-root users can access it\nENV UV_PYTHON_INSTALL_DIR=/app/.python\nRUN uv sync --frozen --no-dev --python 3.13 --package \u003cpackage-name\u003e\n\nENTRYPOINT [\"/app/.venv/bin/python\", \"-m\", \"\u003cpackage_module\u003e.main\"]\n```\n\n### Non-workspace dependencies\n\nAny `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 \u003cpackage\u003e` is not allowed.\n\n## Pull Request Guidelines\n\n### Cross-Repo Dependency Ordering\n\n`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:\n\nIf 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.\n\n### Dependency Pinning\n\nAll external package dependencies must use the compatible release operator (`~=`). Do not use `\u003e=` as it leaves the version unbounded. Exact pins (`==`) are acceptable when a package requires a specific version.\n\n### Code Standards\n\nWhen 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.\n\nIt 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.\n\nFor 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.\n\n### IDOR Prevention\n\nWhen reviewing route handlers, watch for authorization gaps that could allow users to access or modify resources belonging to other accounts/patients:\n\n- **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.\n- **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.\n- **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`.\n- **List/query endpoints**: Queries that return collections must scope by `account_id` (or `patient_id` where applicable) to prevent cross-account data leakage.\n- **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.\n\n### Billing Enforcement\n\nAny 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`:\n\n- **`ensure_patient_billing_access_from_path`**: Use when `patient_id` is a path parameter. Add as a `Depends()` dependency on the route.\n- **`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.\n\nBoth 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.\n\n## Commands\n\nNx commands are run with:\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:\u003ccommand\u003e\n```\n\nFor example, to run tests for the `dynamodb-helper` package:\n\n```bash\npnpm exec nx run dynamodb-helper:test\n```\n\nAvailable commands are defined in `nx.json` at the root and in each package's `project.json` file.\n\n### Formatting, Linting, and Type Checking\n\nFor 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:\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:format\npnpm exec nx run \u003cpackage-name\u003e:lint\npnpm exec nx run \u003cpackage-name\u003e:type-check\n```\n\n**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.\n\n## Types\n\nThis repo makes heavy use of Pydantic V2 models. Shared models are typically defined in the `bioscope-types` package.\n\nWe have a `BioscopeBaseModel` class that is a subclass of `BaseModel` that adds some additional functionality, mostly adding camelCase aliases to the fields.\nIn our code, we use snake_case for everything, but anything leaving or entering Python should be camelCase, for example:\n\n- Network requests and responses\n- Database rows\n- Logging statements\n\nThe shared `BioscopeBaseModel` automatically takes care of this for us.\n\n## FastAPI Routes (`packages/**/src/**/routes/**.py`)\n\n### Basic Conventions\n\n- Route functions should be async\n- Router should have a common prefix per file\n- Follow standard REST conventions\n\n### Headers and Authentication\n\nThese routes are configured with an AWS API Gateway. Most routes are secured with a custom lambda authorizer.\n\nThis authorizer validates the Bearer JWT token and extracts the user ID from the token.\nRequests come in with a `Bioscope-Account-Id` header that contains the account ID.\nThe authorizer ensures that the user in the JWT belongs to the account.\nThis means that these headers are \"safe\" and guaranteed to be valid for the calling user.\n\nTherefore, authorization (i.e. to prevent IDOR, etc.) should be done via these headers.\n\nThese headers can be injected into the route function as dependencies using the `BioscopeUserIdHeaderDeps` and `BioscopeAccountIdHeaderDeps` classes.\n\n### Models\n\nRequest and response models should both be Pydantic models that inherit `BioscopeBaseModel`.\n`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.\n\n### Logging\n\nRoutes should use the `BioscopeLoggerDeps` class to inject the logger into the route function.\nThis logger is automatically configured to include the user ID and account ID in the log messages.\n\n#### PII/PHI Logging Rules\n\n**Fields that must NEVER be logged:**\n\n- Patient names, emails, phone numbers, addresses, dates of birth\n- Medical data (diagnoses, medications, lab results, clinical notes)\n- Full request/response bodies from external APIs (FHIR, EHR, lab vendors, etc.)\n- Webhook payloads (these often contain patient data or credentials)\n- Secrets, tokens, API keys, credentials — omit these entirely (no length hints either)\n- Template parameters that contain patient-facing content (e.g., SMS/email body text)\n\n**Safe fields that CAN be logged:**\n\n- Internal UUIDs: `patient_id`, `account_id`, `user_id`, `order_id`, `connection_id`, `correlation_id`\n- Status codes, HTTP methods, URL paths\n- Counts and lengths (e.g., number of records processed, response body length)\n- Template/event names, enum values, operation names\n- Durations, timestamps, retry counts\n\n**Redaction pattern** — when context about a sensitive value is needed for debugging, log a length hint instead of the value:\n\n```python\n# Good — log a length hint for debugging without exposing the value\nlogger.info(\"received webhook\", extra={\"bodyLength\": len(body)})\n\n# Good — log only safe identifiers\nlogger.info(\"processing patient\", extra={\"patientId\": patient_id, \"accountId\": account_id})\n\n# Bad — logs the entire webhook/response body (may contain PII/PHI)\nlogger.info(\"received webhook\", extra={\"body\": body})\nlogger.info(\"API response\", extra={\"response\": response.json()})\n```\n\n**Never log full request/response bodies** — log the status code and body length instead:\n\n```python\n# Good\nlogger.info(\"FHIR response\", extra={\"statusCode\": response.status_code, \"bodyLength\": len(response.content)})\n\n# Bad\nlogger.info(\"FHIR response\", extra={\"body\": response.json()})\n```\n\n**Exception messages** — do not embed API response text in exception messages, as these end up in logs via `logger.exception`:\n\n```python\n# Good\nraise ValueError(f\"EHR API returned {response.status_code}\")\n\n# Bad — response body may contain PHI\nraise ValueError(f\"EHR API error: {response.text}\")\n```\n\n#### Formatting\n\nDo 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).\n\n```python\n# Good\nextra={\"metric\": usage_metric.model_dump()}\n\n# Bad\nextra={\"metric\": usage_metric.model_dump_json()}\nextra={\"metric\": json.dumps(usage_metric.model_dump())}\n```\n\n### HTTP Client\n\n`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`.\n\nWhen testing code that uses `httpx`, use `respx` for mocking. Use the **pytest fixture pattern for this**.\n\n### Relative Versus Absolute Imports\n\nProduction code should always use absolute imports. For example:\n\n```python\nfrom account_service.models import Account  # GOOD\nfrom .models import Account  # BAD\n```\n\nHowever, 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:\n\n```python\nfrom .conftest import build_data  # GOOD\nfrom tests.conftest import build_data  # BAD\n```\n\n### Error Handling\n\nRaise `HTTPException` with appropriate status code and detail message\n\n## Lambda Handlers (`packages/**/handler.py`)\n\n### Handler Types\n\n1. **LambdaHandler** - base handler for non-API Gateway functions\n2. **HttpHandler** - extends LambdaHandler with API Gateway support (requires `lambda-handler[api]`)\n\n### Lazy Loading Pattern\n\nMany 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.\n\n**Solution**: Use lazy loading in `handler.py` files only. Load direct invocation handling code only when needed, and vice versa for API Gateway routes.\n\n**Example**:\n\n```python\nfrom lambda_handler.http_handler import HttpHandler\n\ndef get_app():\n    from my_service.app import app  # noqa: PLC0415\n    return app\n\nhandler = HttpHandler(get_app)\n\n@handler.direct_invocation()\ndef handle_direct_invocation(event: DirectInvocationEvent, logger: BioscopeLogger):\n    from my_service.handlers.handler_one import handle_handler_one  # noqa: PLC0415\n    return handle_handler_one(event, logger)\n```\n\n**Important**:\n\n- Restrict lazy imports to `handler.py` only\n- Keep common imports (logger, types, handler framework) at module level\n- Use `# noqa: PLC0415` to suppress linting warnings\n- Never lazy load in business logic or service modules\n\n### Decorators\n\n| Event Source      | Decorator                    | Required kwarg         | Notes                                    |\n| ----------------- | ---------------------------- | ---------------------- | ---------------------------------------- |\n| SQS               | `@handler.sqs`               | `queue_name=\"\u003cqueue\u003e\"` |                                          |\n| SNS               | `@handler.sns`               | `topic_name=\"\u003ctopic\u003e\"` |                                          |\n| Direct Invocation | `@handler.direct_invocation` | N/A                    | Operation extracted from request model   |\n| Event Bridge      | `@handler.event_bridge`      | N/A                    | Handles all EventBridge events           |\n| API Gateway Auth  | `@handler.authorizer`        | N/A                    | For custom API Gateway authorizers       |\n| Health Check      | `@handler.health_check`      | N/A                    | Custom health check (built-in available) |\n\n**Notes**:\n\n- EventBridge and authorizer handlers do not use operation discriminators - they handle all events of their type sent to the function.\n- Direct invocation handlers automatically extract the `operation` from the request model's `operation` class attribute.\n- A built-in health check handler is automatically registered for all Lambda functions and responds to `{\"operation\": \"healthCheck\"}` requests.\n\n### Message Payloads\n\n• Define a Pydantic model that **inherits `BioscopeBaseModel`** for every distinct message body.\n• Models should be defined in the `bioscope_types` package under the `services` module.\n\nAlways annotate the first parameter with the corresponding event model from `lambda_handler.models`, e.g. `SqsEvent[MyMessage]`.\n`MyMessage` should be a new Pydantic model that inherits `BioscopeBaseModel`.\n`BioscopeBaseModel` automatically handles camelCase to snake_case conversion for all fields.\n\n### Dependency Injection\n\nHandler functions may declare these optional parameters which will be injected automatically:\n\n- `logger: BioscopeLogger` - the project-wide structured logger.\n- `context: LambdaContext` - the AWS Lambda context object.\n\n### Example (SQS)\n\n```python\nfrom lambda_handler.handler import LambdaHandler\nfrom lambda_handler.models.sqs import SqsEvent\nfrom bioscope_types.common import BioscopeBaseModel\n\nhandler = LambdaHandler()\n\nclass MySqsMessage(BioscopeBaseModel):\n    my_custom_field: str\n\n@handler.sqs(queue_name=\"my-queue\")\ndef handle_sqs_event(event: SqsEvent[MySqsMessage], logger, context):\n    logger.info(\"processing message\", extra={\"myCustomField\": event.body.my_custom_field})\n```\n\n### Style Rules\n\n- Use **explicit type annotations** everywhere.\n- Keep handler bodies minimal; delegate business logic to service modules.\n- Use the provided `logger`, not `print`, for output.\n- 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.\n\n### Handler Organization (`packages/**/src/**/handlers/**/*.py`)\n\nFor services with many direct invocation handlers, organize them in a dedicated `handlers` directory rather than implementing the business logic directly in `handler.py`.\n\n### Structure\n\n```text\nsrc/\n  service_name/\n    handler.py          # Contains @handler.direct_invocation decorators\n    handlers/\n      __init__.py       # Exports all handler functions\n      handler_one.py    # Individual handler implementation\n      handler_two.py    # Individual handler implementation\n```\n\n### Handler Function Signature\n\nHandler functions should follow this standardized signature:\n\n```python\nasync def handle_operation_name(\n    args: OperationArgs,\n    logger: BioscopeLogger,\n) -\u003e OperationResponse:\n    # Implementation here\n```\n\nWhere:\n\n- `args` is the operation's arguments model from `bioscope_types.services`\n- `logger` is the structured logger instance\n- Return type matches the operation's response model\n\n### Main Handler File\n\nThe main `handler.py` file should delegate to the individual handlers:\n\n```python\nfrom service_name.handlers import handle_operation_name\n\n@handler.direct_invocation()\nasync def operation_name_handler(\n    event: OperationRequest, parent_logger: BioscopeLogger\n) -\u003e OperationResponse:\n    return await handle_operation_name(\n        args=event.args,\n        logger=parent_logger.child(\n            {\n                # Add relevant fields from event.args (in camelCase and avoiding PHI/PII)\n            }\n        ),\n    )\n```\n\n## AWS Services (`packages/**/src/**/aws.py`)\n\n**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`).\n\n### AWS Abstraction Pattern\n\nCreate `src/package_name/aws.py`:\n\n```python\nfrom contextlib import asynccontextmanager\nfrom aioboto3 import Session\n\nsession = Session()\n\n@asynccontextmanager\nasync def get_service_name():\n    async with session.client(\"service-name\") as client:\n        yield client\n```\n\n### Usage in Production Code\n\n```python\nfrom package_name.aws import get_service_name\n\nasync def some_operation() -\u003e None:\n    async with get_service_name() as client:\n        await client.some_api_call()\n```\n\n## Testing (`packages/**/tests/**/*.py`)\n\n### Basic Rules\n\n- Prefer **pytest** for all unit tests.\n- 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.\n- Tests are all run with `asyncio_mode = \"auto\"` in `pyproject.toml`, so tests don't need to be marked as async individually.\n- **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)\n- Use pytest fixtures for both mocking and for defining common test data.\n- 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.\n- 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.\n\n### Test Structure\n\n- Mirror source code structure in test organization\n- Individual classes for each function being tested\n- Individual methods for each test case\n\nExample:\n\n```python\nclass TestCopyS3ToTemp:\n    def test_happy_path(self):\n        pass\n\n    def test_invalid_url_format(self):\n        pass\n\n    def test_s3_error(self):\n        pass\n```\n\n### Assertions\n\nWhen performing assertions on data, compare the entire object as much as possible rather than individual assertions for each field.\n\nFor example, instead of:\n\n```python\nassert result is not None\nassert len(result) == 1\nassert result[0].id == \"123\"\nassert result[0].name == \"John Doe\"\nassert result[0].email == \"john.doe@example.com\"\n```\n\nyou should do:\n\n```python\nassert result == [User(\n    id=\"123\",\n    name=\"John Doe\",\n    email=\"john.doe@example.com\"\n)]\n```\n\nWhen 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.\nFor example, instead of:\n\n```python\nassert mock_foo.call_args.args == (\"123\", \"John Doe\", \"john.doe@example.com\")\n```\n\nyou should do:\n\n```python\nmock_foo.assert_called_once_with(\"123\", \"John Doe\", \"john.doe@example.com\")\n```\n\n### Async vs Sync Assertions\n\n**IMPORTANT**: For async functions (using `AsyncMock`), use `assert_awaited...` methods:\n\n- `assert_awaited_once()` instead of `assert_called_once()`\n- `assert_awaited_once_with(args)` instead of `assert_called_once_with(args)`\n- `assert_not_awaited()` instead of `assert_not_called()`\n\nFor sync functions (using `MagicMock`), use `assert_called...` methods:\n\n- `assert_called_once()`\n- `assert_called_once_with(args)`\n- `assert_not_called()`\n\n### Positive and Negative Assertions\n\nAlways include both positive assertions (what should happen) and negative assertions (what should NOT happen) to ensure functions aren't being called unexpectedly.\n\n### Mocking\n\nAs 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.\n\nMocks 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.\n\n#### AWS Service Mocking\n\nWhen testing code that uses AWS services, follow this pattern (see [AWS Services](#aws-services-packagessrcawspy) section for the production abstraction):\n\n**Create AWS abstraction** (`src/package_name/aws.py`):\n\n```python\nfrom contextlib import asynccontextmanager\nfrom aioboto3 import Session\n\nsession = Session()\n\n@asynccontextmanager\nasync def get_s3():\n    async with session.client(\"s3\") as s3_client:\n        yield s3_client\n```\n\n**Use abstraction in production code**:\n\n```python\nfrom package_name.aws import get_s3\n\nasync def upload_file(bucket: str, key: str, content: bytes) -\u003e None:\n    async with get_s3() as s3:\n        await s3.put_object(Bucket=bucket, Key=key, Body=content)\n```\n\n**Test with botocore stubber**:\n\n```python\nfrom collections.abc import AsyncGenerator\nfrom contextlib import asynccontextmanager\nimport pytest\nfrom aioboto3 import Session\nfrom botocore.stub import Stubber\nfrom pytest_mock import MockerFixture, MockType\n\n@pytest.fixture(autouse=True)\ndef fake_aws_env(monkeypatch: pytest.MonkeyPatch) -\u003e None:\n    monkeypatch.setenv(\"AWS_ACCESS_KEY_ID\", \"testing\")\n    monkeypatch.setenv(\"AWS_SECRET_ACCESS_KEY\", \"testing\")\n    monkeypatch.setenv(\"AWS_SESSION_TOKEN\", \"testing\")\n    monkeypatch.setenv(\"AWS_DEFAULT_REGION\", \"us-east-2\")\n\n@pytest.fixture\ndef mock_get_s3(mocker: MockerFixture) -\u003e MockType:\n    return mocker.patch(\"package_name.client.get_s3\")\n\n@pytest.fixture\nasync def s3_stub(mock_get_s3: MockType) -\u003e AsyncGenerator[Stubber]:\n    session = Session()\n    async with session.client(\"s3\", region_name=\"us-east-2\") as s3_client:\n        stubber = Stubber(s3_client)\n        stubber.activate()\n\n        @asynccontextmanager\n        async def _fake_get_s3():\n            yield s3_client\n\n        mock_get_s3.side_effect = _fake_get_s3\n        yield stubber\n        stubber.assert_no_pending_responses()\n        stubber.deactivate()\n\nclass TestUploadFile:\n    async def test_upload_success(self, s3_stub: Stubber):\n        s3_stub.add_response(\n            \"put_object\",\n            {},\n            {\n                \"Bucket\": \"test-bucket\",\n                \"Key\": \"test-key\",\n                \"Body\": b\"test-content\",\n            },\n        )\n\n        await upload_file(\"test-bucket\", \"test-key\", b\"test-content\")\n```\n\nThis `aws.py` file itself should be added to the `omit` list in the `pyproject.toml` file of the package. For example:\n\n```toml\nomit = [\n    \"src/\u003cpackage_name\u003e/aws.py\",\n]\n```\n\n### Running Tests\n\n```bash\npnpm exec nx run \u003cpackage-name\u003e:test\n```\n\n### Fixtures\n\n#### Logger Fixture\n\n**IMPORTANT**: Always use a real `BioscopeLogger` instance in tests, not a mock. Create a `conftest.py` file in your package's test directory:\n\n```python\nimport pytest\nfrom bioscope_logger import BioscopeLogger, get_logger\nfrom uuid import uuid4\n\n@pytest.fixture\ndef logger() -\u003e BioscopeLogger:\n    return get_logger(\"package-name\", uuid4())\n```\n\nThis 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.\n\n#### Other Fixtures\n\nExample:\n\n```python\nfrom unittest.mock import AsyncMock, MagicMock\nfrom pytest_mock import MockerFixture\nfrom models import Patient\n\n@pytest.fixture\ndef patient() -\u003e Patient:\n    return Patient(\n        id=\"123\",\n        name=\"John Doe\",\n    )\n\n@pytest.fixture\ndef mock_get_patient(mocker: MockerFixture) -\u003e AsyncMock:\n    return mocker.patch(\"some_service.utils.get_patient\")\n\n@pytest.fixture\ndef mock_sync_function(mocker: MockerFixture) -\u003e MagicMock:\n    return mocker.patch(\"some_service.utils.sync_function\")\n\nclass TestMyFunction:\n    async def test_happy_path(self, patient: Patient, mock_get_patient: AsyncMock):\n        mock_get_patient.return_value = patient\n        # Use assert_awaited_once_with for async mocks\n        mock_get_patient.assert_awaited_once_with(\"patient_id\")\n\n    def test_sync_function(self, mock_sync_function: MagicMock):\n        mock_sync_function.return_value = \"result\"\n        # Use assert_called_once_with for sync mocks\n        mock_sync_function.assert_called_once_with(\"arg\")\n```\n\n**Fixture Type Guidelines**:\n\n- Use `MagicMock` for synchronous functions\n- Use `AsyncMock` for asynchronous functions\n- pytest-mock automatically creates the correct mock type, but explicit typing helps with IDE support\n\n### Test Coverage\n\nAlways aim for 100% coverage. `#pragma: no cover` can be used to exclude specific lines from coverage.\n\n### Do NOT create `__init__.py` files in test directories\n\nYou should NEVER create an `__init__.py` file in a test directory. Doing so will break the VSCode/Cursor test explorer.\n\n## Querying Logs in Axiom\n\nUse 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.\n\nLogs 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**.\n\n### Key Fields\n\n| Field                                  | Description                                                |\n| -------------------------------------- | ---------------------------------------------------------- |\n| `_time`                                | Timestamp                                                  |\n| `logGroup`                             | CloudWatch log group (e.g., `/aws/lambda/account-service`) |\n| `message`                              | Log message                                                |\n| `levelname`                            | Log level (`INFO`, `ERROR`, etc.)                          |\n| `service`                              | Service name                                               |\n| `correlationId`                        | UUID for tracing requests across services                  |\n| `accountId`, `userId`, `patientId`     | Entity identifiers                                         |\n| `path`, `method`, `statusCode`, `took` | HTTP request details                                       |\n| `errorMessage`, `errorType`            | Error details                                              |\n| `data`                                 | Object containing extra fields not in the standard set     |\n\n### Example Queries\n\n```apl\n// Errors in a service\n['bioscope-dev']\n| where levelname == \"ERROR\" and logGroup == \"/aws/lambda/account-service\"\n\n// Trace a request across services\n['bioscope-dev']\n| where correlationId == \"550e8400-e29b-41d4-a716-446655440000\"\n| order by _time asc\n\n// Slow requests\n['bioscope-dev']\n| where took \u003e 1000\n| project _time, service, path, took\n\n// Error counts by service (last hour)\n['bioscope-dev']\n| where _time \u003e ago(1h) and levelname == \"ERROR\"\n| summarize count() by logGroup\n```"])</script><script>self.__next_f.push([1,"1d:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$23\",\"previewLines\":8}]]}]\n1e:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"@AGENTS.md\",\"previewLines\":8}]]}]\n24:T1ea2,"])</script><script>self.__next_f.push([1,"# Claude Code Rules for Bioscope Web App\n\n## Design System and Styling\n\n### Color Usage\n**NEVER hardcode color values in components.** All colors must be defined in the design system.\n\n- ❌ **WRONG**: `bg-[#181f2e]`, `border-[#303a48]`, `text-[#8fbecc]`\n- ✅ **CORRECT**: `bg-tab-nav-background`, `border-tab-nav-border`, `text-tab-active-indicator`\n\n#### Process for Adding New Colors:\n1. Add the color variable to `@theme inline` section in `src/index.css`:\n   ```css\n   --color-new-color-name: var(--new-color-name);\n   ```\n\n2. Add the oklch value to `:root` section in `src/index.css`:\n   ```css\n   --new-color-name: oklch(L C H);\n   ```\n\n3. Use the Tailwind class in components:\n   ```tsx\n   className=\"bg-new-color-name\"\n   ```\n\n#### Color Conversion:\nWhen converting hex colors to oklch:\n- Use online tools or color conversion utilities\n- Maintain the exact visual appearance\n- Document the original hex value in a comment if needed\n\n### Component Styling Guidelines\n- Always use the existing design system tokens\n- Check `src/index.css` for available color variables before adding new ones\n- Prefer semantic color names (e.g., `tab-nav-background`) over generic names (e.g., `dark-blue-1`)\n- Follow the existing naming conventions in the design system\n\n### Typography\n**Always use the Typography component for text rendering.** Never use raw HTML text elements or hardcoded font styles.\n\n#### Typography Component Usage\nThe Typography component is located at `src/components/base/typography.tsx` and should be used for all text:\n\n```tsx\nimport { Typography } from \"@/components/base/typography\";\n\n\u003cTypography variant=\"section-title\" color=\"primary\"\u003e\n  My Text\n\u003c/Typography\u003e\n```\n\n#### Available Typography Variants\n- `header` - Semibold 20px, for main headers\n- `large-title` - Semibold 20px, for large titles\n- `section-title` - Semibold 16px, for section headers\n- `section-content` - Normal 14px, for section body text\n- `attribute-label` - Normal 16px, for attribute labels\n- `key-value-key` - Semibold 14px, for key-value pair keys\n- `key-value-value` - Normal 14px, for key-value pair values\n- `button-label` - Bold 14px, for button text\n- `chip-label` - Medium 12px, for chip/badge text\n- `input-label` - Medium 14px, for form input labels\n- `input-helper` - Normal 12px, for input helper text\n- `input-text` - Medium 16px, for input field text\n- `detail-label` - Medium 12px, for detail labels\n- `detail-subtext` - Normal 12px, for detail subtext\n- `table-header` - Light 12px, for table headers\n- `table-cell` - Normal 14px, for table cells\n- `list-button-label` - Normal 20px, for list button labels\n\n#### Available Typography Colors\n- `primary` - Primary text color (text-text-primary)\n- `muted` - Muted text color (text-text-muted)\n- `error` - Error/destructive text color (text-destructive)\n- `secondary` - Secondary foreground color (text-secondary-foreground)\n\n#### When Typography Component Cannot Be Used\nIn 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`:\n\n```tsx\nimport { typographyVariants } from \"@/components/base/typography\";\nimport { cn } from \"@/utils/cn\";\n\n\u003cSomeComponent\n  className={cn(typographyVariants({ variant: \"section-title\", color: \"primary\" }))}\n/\u003e\n```\n\n#### Typography Props\n- `variant` - The typography variant to use (required for consistent styling)\n- `color` - The text color (defaults to primary if not specified)\n- `as` - The HTML element to render (p, span, div, h1-h6, li, pre, code, td, th)\n- `italic` - Boolean flag to apply italic styling\n- `className` - Additional custom classes (use sparingly)\n- `onClick` - Click handler (will add cursor-pointer automatically)\n- `testId` - Test ID for testing purposes\n\n#### Examples\n```tsx\n// Section header\n\u003cTypography variant=\"section-title\" color=\"primary\"\u003e\n  User Information\n\u003c/Typography\u003e\n\n// Body text\n\u003cTypography variant=\"section-content\" color=\"muted\"\u003e\n  This is the description text.\n\u003c/Typography\u003e\n\n// Error message\n\u003cTypography variant=\"input-helper\" color=\"error\"\u003e\n  This field is required\n\u003c/Typography\u003e\n\n// Custom element with typography styles\n\u003cTypography variant=\"header\" as=\"h1\"\u003e\n  Page Title\n\u003c/Typography\u003e\n\n// When Typography component cannot be used\n\u003cCustomButton\n  className={cn(typographyVariants({ variant: \"button-label\", color: \"primary\" }))}\n\u003e\n  Click Me\n\u003c/CustomButton\u003e\n```\n\n## Project Structure\n\n### Directory Organization\n```\nsrc/\n├── assets/          # All static assets\n├── components/      # All reusable components\n│   └── base/        # Basic building blocks (buttons, accordions, etc.)\n│       └── shadcn/  # Shadcn registry components (DO NOT modify or export)\n├── hooks/           # Application-wide hooks\n│   └── api/         # API interaction and TanStack Query hooks\n└── pages/           # Full page components\n```\n\n### Component Structure\n\n#### Simple Components\nSimple, atomic components (like buttons) can be a single file:\n```\nbutton.tsx\n```\n\n#### Complex Components\nComplex components should be organized in directories with subcomponents:\n```\nSelect/\n├── index.tsx        # Main component, exports only what consumers need\n├── hooks/           # Component-specific hooks\n├── utils/           # Component-specific utilities\n└── SelectOption.tsx # Sub-components\n```\n\n### Component Placement\n- Even single-use components should go in `src/components/` if not obviously scoped to a single page\n- Keep components small and composable\n- Avoid code duplication within components\n\n## React and TypeScript\n\n### Component Code Layout\nAll custom (non-shadcn) components should follow this layout:\n\n```tsx\nimport * as React from \"react\";\n\ntype \u003cComponentName\u003eOwnProps = {\n  // Component-specific props\n};\n\nexport type \u003cComponentName\u003eProps = {} \u0026 \u003cComponentName\u003eOwnProps;\n\nfunction \u003cComponentName\u003eComponent({}: \u003cComponentName\u003eProps) {\n  // Component implementation\n}\n\nconst \u003cComponentName\u003e = React.memo(\u003cComponentName\u003eComponent);\n\nexport { \u003cComponentName\u003e };\n```\n\n### Naming Conventions\n- **Files**: camelCase (e.g., `loadingContent.tsx`)\n- **Components**: PascalCase (e.g., `LoadingContent`)\n- **Index files**: Component takes parent directory name (e.g., `loadingContent/index.tsx` → `LoadingContent`)\n\n### Type Imports\nWhen using TypeScript with `verbatimModuleSyntax` enabled:\n- ✅ **CORRECT**: `import type { TypeName } from './module';`\n- ❌ **WRONG**: `import { TypeName } from './module';` (for types)\n\n### Hook Usage\n- Use hooks and custom hooks as needed\n- **Avoid `useRef` and `useEffect` unless absolutely necessary** - they can introduce bugs and hard-to-reason render cycles\n- When needing `useEffect`, consider using hooks from [react-use](https://github.com/streamich/react-use) for more direct, obvious, and opinionated code flow\n\n### Navigation\n- Always use `void navigate()` to handle promise returns from React Router\n- Mark button types explicitly: `\u003cbutton type=\"button\"\u003e`\n\n### Shadcn Components\n**CRITICAL**: Shadcn components live in `src/components/base/shadcn/` and have strict usage rules:\n\n- ❌ **NEVER** modify shadcn components\n- ❌ **NEVER** export shadcn components from `src/components/base/`\n- ❌ **NEVER** import shadcn components directly outside of `src/components/base/`\n- ✅ **ALWAYS** create a wrapper in `src/components/base/` for shadcn components before using them\n\nExample:\n```tsx\n// src/components/base/button.tsx\nimport { Button as ShadcnButton } from \"./shadcn/button\";\n\nexport function Button(props) {\n  return \u003cShadcnButton {...props} /\u003e;\n}\n```\n\n## General Code Quality\n- Follow existing patterns in the codebase\n- Use memoization for expensive computations\n- Ensure accessibility (ARIA labels, semantic HTML)\n- Test mobile responsiveness for all UI components"])</script><script>self.__next_f.push([1,"20:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$24\",\"previewLines\":8}]]}]\n25:T6de,"])</script><script>self.__next_f.push([1,"# Claude Development Rules\n\n## Component Organization\n\n### Multiple Components Per File\n\n**Rule**: Do not place multiple components in the same file. Each component should be organized into its own directory structure.\n\n**Structure**: When a component contains sub-components or helper functions:\n\n1. Create a directory with the component name\n2. Create an `index.tsx` file for the main component export\n3. Create separate files for each sub-component\n4. Create a `utils.ts` file for helper functions and utilities\n\n**Example**:\n\n```\nComponentName/\n├── index.tsx           # Main component export\n├── SubComponentA.tsx   # Sub-component A\n├── SubComponentB.tsx   # Sub-component B\n└── utils.ts            # Helper functions\n```\n\n**Benefits**:\n\n- Improved code organization and maintainability\n- Easier to locate and modify specific components\n- Better separation of concerns\n- Cleaner git diffs and easier code reviews\n- Simpler testing of individual components\n\n**Bad Example** ❌:\n\n```tsx\n// MyModal.tsx\nexport function MyModal() { ... }\nfunction ModalHeader() { ... }\nfunction ModalBody() { ... }\nfunction formatDate() { ... }\n```\n\n**Good Example** ✅:\n\n```\nMyModal/\n├── index.tsx          # exports MyModal\n├── ModalHeader.tsx    # exports ModalHeader\n├── ModalBody.tsx      # exports ModalBody\n└── utils.ts           # exports formatDate\n```\n\n## Logging and Event Tracking\n\n**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."])</script><script>self.__next_f.push([1,"21:[\"$\",\"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\"}]]}],[\"$\",\"$L11\",null,{\"content\":\"$25\",\"previewLines\":8}]]}]\n"])</script></body></html>

package/.next/standalone/.next/server/app/rules.meta ADDED Viewed

@@ -0,0 +1,15 @@
+{
+  "headers": {
+    "x-nextjs-stale-time": "300",
+    "x-nextjs-prerender": "1",
+    "x-next-cache-tags": "_N_T_/layout,_N_T_/rules/layout,_N_T_/rules/page,_N_T_/rules"
+  },
+  "segmentPaths": [
+    "/_tree",
+    "/_full",
+    "/rules/__PAGE__",
+    "/rules",
+    "/_index",
+    "/_head"
+  ]
+}