Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (77 loc) · 4.39 KB

AGENTS.md

File metadata and controls

107 lines (77 loc) · 4.39 KB

AGENTS.md

Overview

Protocol Guide is a Node.js/TypeScript monorepo-style app centered on a jurisdiction-aware EMS protocol search product. The core constraint is that protocol search must be scoped to the user's county or agency, not treated as national guidance.

Required Context

  • Read CLAUDE.md first for project-specific rules and domain constraints.
  • The most important architectural reference is docs/EMS_ARCHITECTURE.md.
  • Prefer existing patterns already used in app/, server/, hooks/, lib/, and drizzle/.
  • Keep files under 500 lines when practical; split by responsibility.

Common Commands

Install and develop

pnpm install
pnpm dev          # server :3001 + web :8081
pnpm dev:server   # backend only
pnpm dev:metro    # Expo web frontend only

Quality checks

pnpm check        # TypeScript
pnpm lint         # Expo/ESLint
pnpm test         # Vitest suite
pnpm test:integration
pnpm test:e2e

Targeted test runs

pnpm test tests/integration/user-journey.test.ts
pnpm test:watch
vitest run tests/path/to/file.test.ts

Build and database

pnpm build        # server bundle
pnpm build:web    # Expo web export + PWA/SEO steps
pnpm db:push      # drizzle generate + migrate

Architecture Map

Frontend

  • app/ is the Expo Router app.
  • app/(tabs)/index.tsx is the main search experience.
  • components/search/ contains the reusable jurisdiction/search UI.
  • hooks/ contains app behavior such as auth, search, voice, disclaimer, offline caching, and county restrictions.
  • lib/trpc.ts creates the typed client and keeps superjson inside httpBatchLink.

Backend

  • server/_core/index.ts is the Express entrypoint.
  • tRPC setup lives in server/_core/trpc.ts; use existing procedure types like publicProcedure, protectedProcedure, csrfProtectedProcedure, rateLimitedProcedure, and userAwareRateLimitedProcedure.
  • Router composition is split under server/routers/; search routes are organized under server/routers/search/ rather than a single search.ts file.
  • _core/ contains shared backend infrastructure: tracing, middleware, auth/session handling, embeddings, RAG orchestration, resilience, and Claude integration.

Data model

  • drizzle/schema.ts is the schema source of truth.
  • There are two important data domains:
    • Drizzle-managed application tables such as users, agencies, bookmarks, search_history, subscriptions, invitations, and analytics.
    • Production Supabase protocol corpus tables such as manus_protocol_chunks, manus_agencies, and county_agency_mapping.
  • county_agency_mapping is the critical bridge from user county selection to the agency-specific protocol corpus.

Core Product Flow

The central workflow is:

  1. Normalize EMS query terms and abbreviations.
  2. Resolve county to agency through county_agency_mapping.
  3. Generate embeddings and run agency-scoped vector search against manus_protocol_chunks.
  4. Re-rank results with protocol-aware scoring.
  5. Generate a retrieval-only Claude response with mandatory protocol citations.

Safety-critical queries like medication dosing, contraindications, emergent conditions, and pediatric medication questions trigger enhanced retrieval behavior.

Coding Conventions To Preserve

  • Use explicit TypeScript types; avoid any.
  • Use Zod for runtime validation in routers.
  • Use TRPCError with clear error codes.
  • Match existing naming: kebab-case files, PascalCase components/types, camelCase functions, UPPER_SNAKE_CASE constants.
  • Do not bypass jurisdiction scoping in search-related work.
  • For auth and sensitive mutations, preserve existing CSRF and rate-limit middleware patterns.

Testing Expectations

  • After code changes, run at least the relevant validators from pnpm check, pnpm lint, and the affected Vitest tests.
  • Run broader suites before finishing when the change touches shared infrastructure.
  • Integration tests rely on database setup described in tests/integration/README.md.

Important Notes For Future Agents

  • This repo contains many docs, but CLAUDE.md, README.md, docs/EMS_ARCHITECTURE.md, docs/BACKEND.md, and docs/FRONTEND.md provide the fastest accurate orientation.
  • Some older template-style docs exist; prefer the current project-specific router structure and schema over generic examples.
  • If you need search routes, inspect server/routers/search/index.ts and its sibling modules.