# cryptotweezer/pitsypet architecture

> Architecture diagram of the GitHub repository cryptotweezer/pitsypet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cryptotweezer/pitsypet
- Repository: https://github.com/cryptotweezer/pitsypet

## Overview

#### Purpose and Runtime
This is a Next.js App Router application for pet-health management: authenticated users manage pet records, medications, symptoms, appointments, veterinary contacts, and AI-assisted health assessments. It runs as a TypeScript web application with server-rendered routes, client components, and route-handler APIs.
- `src/app/layout.tsx`
- `src/app/page.tsx`
- `src/middleware.ts`

#### Route Domains and User Entry Points
The public landing page leads into separate authenticated application and dashboard route groups. Pet-centric workflows use slugged pet URLs and assessment IDs/sequences; account, billing, clinic, history, and appointment views live under the dashboard.
- `src/app/(app)/pets/[slug]/page.tsx`
- `src/app/(app)/assessment/[id]/page.tsx`
- `src/app/(dashboard)/dashboard/page.tsx`

#### Identity, Authorization, and Data Boundary
Supabase is the primary backend boundary for authentication and Postgres persistence. Middleware and server/client/admin Supabase adapters establish request-specific access; migrations define profiles, pets, assessments, medical records, vector knowledge, search, and row-level-security policies.
- `src/lib/supabase/middleware.ts`
- `src/lib/supabase/server.ts`
- `supabase/migrations/20260619001200_rls_policies.sql`

#### Pet Medical Record Lifecycle
The pet API is the core record-management surface: it owns pet CRUD, soft-delete/restore/purge operations, and nested appointment, medication, and active-symptom resources. UI forms and sections consume this domain, while validation modules define request boundaries.
- `src/app/api/pets/[id]/route.ts`
- `src/app/api/pets/[id]/symptoms/reconcile/route.ts`
- `src/components/pets/pet-form.tsx`

#### Assessment and AI Triage Pipeline
Assessment routes orchestrate conversational symptom collection, classification/safety controls, retrieval-augmented veterinary knowledge, formatting, and fallback behavior. Results are persisted/displayed as clinical reasoning, risk, recommendations, and emergency guidance; assessment output can be exported for veterinary use.
- `src/app/api/assessment/chat/route.ts`
- `src/lib/ai/rag.ts`
- `src/components/assessment/results/results-view.tsx`

#### Knowledge Retrieval and Safety Controls
The AI layer is explicitly decomposed into schemas, classification, embeddings, RAG, safety, cost controls, and fallback handling. Supabase migrations provide veterinary knowledge, first-aid/emergency content, vector search, and audit support; these form the grounding boundary rather than treating model output as standalone advice.
- `src/lib/ai/safety.ts`
- `src/lib/ai/embed.ts`
- `supabase/migrations/20260619001000_vector_search_function.sql`

#### External Services and Operational Integrations
Stripe supports subscription checkout, billing portal access, and webhook-driven billing state. PostHog provides client analytics; Sentry instrumentation supports error monitoring; Arcjet/rate-limit utilities indicate request protection. Assessment export produces a vet-oriented document/summary.
- `src/app/api/billing/webhook/route.ts`
- `src/lib/stripe.ts`
- `src/instrumentation.ts`

Main entry points: [`src/app/(app)/pets/[slug]/page.tsx`](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/(app)/pets/%5Bslug%5D/page.tsx) (Pet app routes), [`src/app/api/assessment/chat/route.ts`](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/assessment/chat/route.ts) (Assessment chat API), [`src/lib/supabase/server.ts`](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/supabase/server.ts) (Supabase server adapter), [`src/app/api/pets/[id]/route.ts`](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/pets/%5Bid%5D/route.ts) (Pet record API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js Web App"]
  node_landing["Landing page<br/>public route<br/>[page.tsx]"]
  node_app_routes["Pet app routes<br/>authenticated routes<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>authenticated route<br/>[page.tsx]"]
  node_request_middleware["Request middleware<br/>auth middleware<br/>[middleware.ts]"]
end

subgraph group_pet["Pet Records"]
  node_pet_api{{"Pet record API<br/>route handler<br/>[route.ts]"}}
  node_symptom_reconcile{{"Symptom reconciliation<br/>route handler<br/>[route.ts]"}}
  node_pet_form["Pet forms<br/>client component<br/>[pet-form.tsx]"]
end

subgraph group_ai["Assessment AI"]
  node_assessment_chat{{"Assessment chat API<br/>route handler<br/>[route.ts]"}}
  node_ai_safety["Safety controls<br/>AI safety layer<br/>[safety.ts]"]
  node_rag["Veterinary RAG<br/>AI retrieval layer<br/>[rag.ts]"]
  node_embeddings["Knowledge embeddings<br/>AI indexing<br/>[embed.ts]"]
  node_assessment_results["Assessment results<br/>client component<br/>[results-view.tsx]"]
end

subgraph group_data["Data &amp; Identity"]
  node_supabase_adapter["Supabase server adapter<br/>backend adapter<br/>[server.ts]"]
  node_supabase[("Supabase Auth &amp; Postgres<br/>managed backend")]
  node_rls_policies["RLS policies<br/>database migration"]
  node_vector_search["Vector search<br/>database migration"]
end

subgraph group_operations["Billing &amp; Operations"]
  node_stripe["Stripe billing<br/>payment integration<br/>[stripe.ts]"]
  node_billing_webhook{{"Billing webhook<br/>route handler<br/>[route.ts]"}}
  node_instrumentation["Error monitoring<br/>instrumentation<br/>[instrumentation.ts]"]
end

node_landing -->|"sign in"| node_app_routes
node_landing -->|"sign in"| node_dashboard
node_request_middleware -->|"guards"| node_app_routes
node_request_middleware -->|"guards"| node_dashboard
node_request_middleware -->|"auth context"| node_supabase_adapter
node_app_routes -->|"renders"| node_pet_form
node_pet_form -->|"manages pets"| node_pet_api
node_app_routes -->|"loads records"| node_pet_api
node_pet_api -->|"active symptoms"| node_symptom_reconcile
node_pet_api -->|"persists"| node_supabase_adapter
node_assessment_chat -->|"screens input/output"| node_ai_safety
node_assessment_chat -->|"grounds reasoning"| node_rag
node_rag -->|"queries vectors"| node_embeddings
node_rag -->|"retrieves knowledge"| node_vector_search
node_assessment_chat -->|"stores assessment"| node_supabase_adapter
node_app_routes -->|"submits assessment"| node_assessment_chat
node_assessment_chat -->|"returns triage"| node_assessment_results
node_supabase_adapter -->|"accesses"| node_supabase
node_rls_policies -.->|"protects data"| node_supabase
node_vector_search -.->|"extends search"| node_supabase
node_dashboard -->|"billing actions"| node_stripe
node_billing_webhook -->|"receives events"| node_stripe
node_billing_webhook -->|"updates billing state"| node_supabase_adapter
node_instrumentation -.->|"monitors errors"| node_app_routes

click node_landing "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/page.tsx"
click node_app_routes "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/(app)/pets/%5Bslug%5D/page.tsx"
click node_dashboard "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_request_middleware "https://github.com/cryptotweezer/pitsypet/blob/main/src/middleware.ts"
click node_pet_api "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/pets/%5Bid%5D/route.ts"
click node_symptom_reconcile "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/pets/%5Bid%5D/symptoms/reconcile/route.ts"
click node_pet_form "https://github.com/cryptotweezer/pitsypet/blob/main/src/components/pets/pet-form.tsx"
click node_assessment_chat "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/assessment/chat/route.ts"
click node_ai_safety "https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/safety.ts"
click node_rag "https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/rag.ts"
click node_embeddings "https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/embed.ts"
click node_assessment_results "https://github.com/cryptotweezer/pitsypet/blob/main/src/components/assessment/results/results-view.tsx"
click node_supabase_adapter "https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/supabase/server.ts"
click node_rls_policies "https://github.com/cryptotweezer/pitsypet/blob/main/supabase/migrations/20260619001200_rls_policies.sql"
click node_vector_search "https://github.com/cryptotweezer/pitsypet/blob/main/supabase/migrations/20260619001000_vector_search_function.sql"
click node_stripe "https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/stripe.ts"
click node_billing_webhook "https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/billing/webhook/route.ts"
click node_instrumentation "https://github.com/cryptotweezer/pitsypet/blob/main/src/instrumentation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_app_routes,node_dashboard,node_request_middleware toneBlue
class node_pet_api,node_symptom_reconcile,node_pet_form toneAmber
class node_assessment_chat,node_ai_safety,node_rag,node_embeddings,node_assessment_results toneMint
class node_supabase_adapter,node_supabase,node_rls_policies,node_vector_search toneRose
class node_stripe,node_billing_webhook,node_instrumentation toneIndigo
```

## Components

### Next.js Web App

- [Landing page](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/page.tsx): public route · Entry point into authenticated product areas. · `src/app/page.tsx`
- [Pet app routes](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/(app)/pets/%5Bslug%5D/page.tsx): authenticated routes · Pet-centric pages use pet slugs and assessment IDs. · `src/app/(app)/pets/[slug]/page.tsx`
- [Dashboard](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/(dashboard)/dashboard/page.tsx): authenticated route · Account, billing, clinic, history, and appointment views. · `src/app/(dashboard)/dashboard/page.tsx`
- [Request middleware](https://github.com/cryptotweezer/pitsypet/blob/main/src/middleware.ts): auth middleware · Establishes request authentication and route access. · `src/middleware.ts`

### Pet Records

- [Pet record API](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/pets/%5Bid%5D/route.ts): route handler · Owns pet lifecycle and nested medical resources. · `src/app/api/pets/[id]/route.ts`
- [Symptom reconciliation](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/pets/%5Bid%5D/symptoms/reconcile/route.ts): route handler · Updates active symptoms within the pet record lifecycle. · `src/app/api/pets/[id]/symptoms/reconcile/route.ts`
- [Pet forms](https://github.com/cryptotweezer/pitsypet/blob/main/src/components/pets/pet-form.tsx): client component · Creates and edits pet records from the UI. · `src/components/pets/pet-form.tsx`

### Assessment AI

- [Assessment chat API](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/assessment/chat/route.ts): route handler · Orchestrates conversational symptom assessment and result persistence. · `src/app/api/assessment/chat/route.ts`
- [Safety controls](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/safety.ts): AI safety layer · Applies classification, safety, cost, and fallback controls. · `src/lib/ai/safety.ts`
- [Veterinary RAG](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/rag.ts): AI retrieval layer · Grounds assessment reasoning in retrieved veterinary knowledge. · `src/lib/ai/rag.ts`
- [Knowledge embeddings](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/ai/embed.ts): AI indexing · Builds vector representations for knowledge retrieval. · `src/lib/ai/embed.ts`
- [Assessment results](https://github.com/cryptotweezer/pitsypet/blob/main/src/components/assessment/results/results-view.tsx): client component · Displays clinical reasoning, risk, recommendations, and emergency guidance. · `src/components/assessment/results/results-view.tsx`

### Data & Identity

- [Supabase server adapter](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/supabase/server.ts): backend adapter · Provides request-scoped authenticated database access. · `src/lib/supabase/server.ts`
- **Supabase Auth & Postgres**: managed backend · Primary identity and persistence boundary with row-level security.
- [RLS policies](https://github.com/cryptotweezer/pitsypet/blob/main/supabase/migrations/20260619001200_rls_policies.sql): database migration · Defines protected access to profiles, pets, assessments, and records. · `supabase/migrations/20260619001200_rls_policies.sql`
- [Vector search](https://github.com/cryptotweezer/pitsypet/blob/main/supabase/migrations/20260619001000_vector_search_function.sql): database migration · Provides veterinary knowledge retrieval over vector data. · `supabase/migrations/20260619001000_vector_search_function.sql`

### Billing & Operations

- [Stripe billing](https://github.com/cryptotweezer/pitsypet/blob/main/src/lib/stripe.ts): payment integration · Manages subscriptions, checkout, portal, and billing state. · `src/lib/stripe.ts`
- [Billing webhook](https://github.com/cryptotweezer/pitsypet/blob/main/src/app/api/billing/webhook/route.ts): route handler · Applies Stripe billing events to application state. · `src/app/api/billing/webhook/route.ts`
- [Error monitoring](https://github.com/cryptotweezer/pitsypet/blob/main/src/instrumentation.ts): instrumentation · Initializes Sentry operational error monitoring. · `src/instrumentation.ts`

## Connections

- Landing page → Pet app routes: sign in
- Landing page → Dashboard: sign in
- Request middleware → Pet app routes: guards
- Request middleware → Dashboard: guards
- Request middleware → Supabase server adapter: auth context
- Pet app routes → Pet forms: renders
- Pet forms → Pet record API: manages pets
- Pet app routes → Pet record API: loads records
- Pet record API → Symptom reconciliation: active symptoms
- Pet record API → Supabase server adapter: persists
- Assessment chat API → Safety controls: screens input/output
- Assessment chat API → Veterinary RAG: grounds reasoning
- Veterinary RAG → Knowledge embeddings: queries vectors
- Veterinary RAG → Vector search: retrieves knowledge
- Assessment chat API → Supabase server adapter: stores assessment
- Pet app routes → Assessment chat API: submits assessment
- Assessment chat API → Assessment results: returns triage
- Supabase server adapter → Supabase Auth & Postgres: accesses
- RLS policies → Supabase Auth & Postgres: protects data
- Vector search → Supabase Auth & Postgres: extends search
- Dashboard → Stripe billing: billing actions
- Billing webhook → Stripe billing: receives events
- Billing webhook → Supabase server adapter: updates billing state
- Error monitoring → Pet app routes: monitors errors