# jsr2406/zoolingo- architecture

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

- Interactive diagram: https://gitdiagram.com/jsr2406/zoolingo-
- Repository: https://github.com/jsr2406/zoolingo-

## Overview

ZooLingo is a voice-first animal-sound interpretation and pet-care product. In the main workflow, a caregiver records or selects an animal sound; the API processes and classifies it, applies a confidence gate, turns the interpretation into human-language text, and can return spoken audio. The product also includes pet profiles, health and care records, expert guidance, authentication, and subscription billing. The graph includes these documented capabilities, but some links to unsampled services are left unverified; dashed edges indicate relationships not directly evidenced in the excerpts.

Main entry points: [`backend/app.py`](https://github.com/jsr2406/zoolingo-/blob/main/backend/app.py) (FastAPI application), [`frontend/src/App.jsx`](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/App.jsx) (Web application), [`backend/petcare/router.py`](https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/router.py) (Pet-care routes), [`backend/services/supabase_client.py`](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/supabase_client.py) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Caregiver experience"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_recorder["Audio recorder<br/>[AudioRecorder.jsx]"]
  node_demo_sounds["Demo sound selector"]
  node_history["History panel<br/>[HistoryPanel.jsx]"]
  node_toast["Toast notifications<br/>[Toast.jsx]"]
end

subgraph group_voice["Voice interpretation"]
  node_api["FastAPI application<br/>[app.py]"]
  node_audio["Audio processing<br/>[audio_processor.py]"]
  node_classifier["Deterministic classifier<br/>[ai_classifier.py]"]
  node_yamnet["YAMNet classifier"]
  node_translation["Text translation<br/>[nlp_translator.py]"]
  node_sarvam_llm["Sarvam LLM translation<br/>[sarvam_llm.py]"]
  node_sarvam_tts["Sarvam speech"]
  node_murf["Murf speech fallback"]
  node_elevenlabs["Sound-effect demos<br/>[elevenlabs_sfx.py]"]
end

subgraph group_care["Pet care"]
  node_petcare_api["Pet-care routes<br/>[router.py]"]
  node_expert["Care guidance engine<br/>[expert_engine.py]"]
  node_pet_db[("Pet-care database<br/>[database.py]")]
  node_supabase[("Supabase client<br/>[supabase_client.py]")]
end

subgraph group_account["Accounts and billing"]
  node_auth_routes["Authentication routes<br/>[auth_router.py]"]
  node_auth["Authentication and quotas<br/>[auth.py]"]
  node_billing["Billing routes<br/>[billing_router.py]"]
  node_payments["Payment adapter<br/>[payment_adapter.py]"]
end

subgraph group_integrations["External services"]
  node_sarvam_service{{"SARVAM AI"}}
  node_murf_service{{"Murf AI"}}
  node_supabase_service[("Supabase")]
  node_payment_service{{"Payment provider"}}
end

node_caregiver(("Caregiver"))

node_caregiver -.->|"uses"| node_webapp
node_webapp -->|"renders"| node_recorder
node_webapp -->|"renders"| node_demo_sounds
node_webapp -->|"renders"| node_history
node_webapp -->|"renders"| node_toast
node_webapp -.->|"sends audio"| node_api
node_api -.->|"processes audio"| node_audio
node_api -->|"predicts"| node_classifier
node_api -->|"tries classification"| node_yamnet
node_api -.->|"translates"| node_translation
node_api -.->|"requests translation"| node_sarvam_llm
node_api -->|"generates speech"| node_sarvam_tts
node_api -->|"falls back"| node_murf
node_api -.->|"serves demos"| node_elevenlabs
node_sarvam_tts -.->|"calls"| node_sarvam_service
node_sarvam_llm -.->|"calls"| node_sarvam_service
node_murf -.->|"calls"| node_murf_service
node_webapp -.->|"uses care features"| node_petcare_api
node_petcare_api -->|"requests advice"| node_expert
node_petcare_api -->|"reads and writes"| node_pet_db
node_pet_db -->|"delegates records"| node_supabase
node_supabase -.->|"accesses"| node_supabase_service
node_auth_routes -->|"verifies users"| node_auth
node_auth_routes -->|"upserts profiles"| node_supabase
node_billing -->|"checks access"| node_auth
node_billing -.->|"handles payments"| node_payments
node_payments -.->|"integrates"| node_payment_service

click node_webapp "https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/App.jsx"
click node_recorder "https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/AudioRecorder.jsx"
click node_demo_sounds "https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/DemoSoundSelector.jsx"
click node_history "https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/HistoryPanel.jsx"
click node_toast "https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/Toast.jsx"
click node_api "https://github.com/jsr2406/zoolingo-/blob/main/backend/app.py"
click node_audio "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/audio_processor.py"
click node_classifier "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/ai_classifier.py"
click node_yamnet "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/yamnet_classifier.py"
click node_translation "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/nlp_translator.py"
click node_sarvam_llm "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/sarvam_llm.py"
click node_sarvam_tts "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/sarvam_integration.py"
click node_murf "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/murf_integration.py"
click node_elevenlabs "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/elevenlabs_sfx.py"
click node_petcare_api "https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/router.py"
click node_expert "https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/expert_engine.py"
click node_pet_db "https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/database.py"
click node_supabase "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/supabase_client.py"
click node_auth_routes "https://github.com/jsr2406/zoolingo-/blob/main/backend/auth_router.py"
click node_auth "https://github.com/jsr2406/zoolingo-/blob/main/backend/auth.py"
click node_billing "https://github.com/jsr2406/zoolingo-/blob/main/backend/billing_router.py"
click node_payments "https://github.com/jsr2406/zoolingo-/blob/main/backend/services/payment_adapter.py"

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_webapp,node_recorder,node_demo_sounds,node_history,node_toast toneBlue
class node_api,node_audio,node_classifier,node_yamnet,node_translation,node_sarvam_llm,node_sarvam_tts,node_murf,node_elevenlabs toneAmber
class node_petcare_api,node_expert,node_pet_db,node_supabase toneMint
class node_auth_routes,node_auth,node_billing,node_payments toneRose
class node_sarvam_service,node_murf_service,node_supabase_service,node_payment_service,node_caregiver toneIndigo
```

## Components

### Caregiver experience

- [Web application](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Audio recorder](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/AudioRecorder.jsx): `frontend/src/components/AudioRecorder.jsx`
- [Demo sound selector](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/DemoSoundSelector.jsx): `frontend/src/components/DemoSoundSelector.jsx`
- [History panel](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/HistoryPanel.jsx): `frontend/src/components/HistoryPanel.jsx`
- [Toast notifications](https://github.com/jsr2406/zoolingo-/blob/main/frontend/src/components/Toast.jsx): `frontend/src/components/Toast.jsx`

### Voice interpretation

- [FastAPI application](https://github.com/jsr2406/zoolingo-/blob/main/backend/app.py): `backend/app.py`
- [Audio processing](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/audio_processor.py): `backend/services/audio_processor.py`
- [Deterministic classifier](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/ai_classifier.py): `backend/services/ai_classifier.py`
- [YAMNet classifier](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/yamnet_classifier.py): `backend/services/yamnet_classifier.py`
- [Text translation](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/nlp_translator.py): `backend/services/nlp_translator.py`
- [Sarvam LLM translation](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/sarvam_llm.py): `backend/services/sarvam_llm.py`
- [Sarvam speech](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/sarvam_integration.py): `backend/services/sarvam_integration.py`
- [Murf speech fallback](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/murf_integration.py): `backend/services/murf_integration.py`
- [Sound-effect demos](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/elevenlabs_sfx.py): `backend/services/elevenlabs_sfx.py`

### Pet care

- [Pet-care routes](https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/router.py): `backend/petcare/router.py`
- [Care guidance engine](https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/expert_engine.py): `backend/petcare/expert_engine.py`
- [Pet-care database](https://github.com/jsr2406/zoolingo-/blob/main/backend/petcare/database.py): `backend/petcare/database.py`
- [Supabase client](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/supabase_client.py): `backend/services/supabase_client.py`

### Accounts and billing

- [Authentication routes](https://github.com/jsr2406/zoolingo-/blob/main/backend/auth_router.py): `backend/auth_router.py`
- [Authentication and quotas](https://github.com/jsr2406/zoolingo-/blob/main/backend/auth.py): `backend/auth.py`
- [Billing routes](https://github.com/jsr2406/zoolingo-/blob/main/backend/billing_router.py): `backend/billing_router.py`
- [Payment adapter](https://github.com/jsr2406/zoolingo-/blob/main/backend/services/payment_adapter.py): `backend/services/payment_adapter.py`

### External services

- **SARVAM AI**
- **Murf AI**
- **Supabase**
- **Payment provider**

### Other components

- **Caregiver**

## Connections

- Caregiver → Web application: uses
- Web application → Audio recorder: renders (evidence: `frontend/src/App.jsx`)
- Web application → Demo sound selector: renders (evidence: `frontend/src/App.jsx`)
- Web application → History panel: renders (evidence: `frontend/src/App.jsx`)
- Web application → Toast notifications: renders (evidence: `frontend/src/App.jsx`)
- Web application → FastAPI application: sends audio
- FastAPI application → Audio processing: processes audio (evidence: `backend/app.py`)
- FastAPI application → Deterministic classifier: predicts (evidence: `backend/app.py`)
- FastAPI application → YAMNet classifier: tries classification (evidence: `backend/app.py`)
- FastAPI application → Text translation: translates (evidence: `backend/app.py`)
- FastAPI application → Sarvam LLM translation: requests translation (evidence: `backend/app.py`)
- FastAPI application → Sarvam speech: generates speech (evidence: `backend/app.py`)
- FastAPI application → Murf speech fallback: falls back (evidence: `backend/app.py`)
- FastAPI application → Sound-effect demos: serves demos (evidence: `backend/app.py`)
- Sarvam speech → SARVAM AI: calls
- Sarvam LLM translation → SARVAM AI: calls
- Murf speech fallback → Murf AI: calls
- Web application → Pet-care routes: uses care features
- Pet-care routes → Care guidance engine: requests advice (evidence: `backend/petcare/router.py`)
- Pet-care routes → Pet-care database: reads and writes (evidence: `backend/petcare/router.py`)
- Pet-care database → Supabase client: delegates records (evidence: `backend/petcare/database.py`)
- Supabase client → Supabase: accesses
- Authentication routes → Authentication and quotas: verifies users (evidence: `backend/auth_router.py`)
- Authentication routes → Supabase client: upserts profiles (evidence: `backend/auth_router.py`)
- Billing routes → Authentication and quotas: checks access (evidence: `backend/billing_router.py`)
- Billing routes → Payment adapter: handles payments (evidence: `backend/billing_router.py`)
- Payment adapter → Payment provider: integrates