# endrigogustavo/mellowpet architecture

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

- Interactive diagram: https://gitdiagram.com/endrigogustavo/mellowpet
- Repository: https://github.com/endrigogustavo/mellowpet

## Overview

MellowPet is a mobile-first emotional-wellbeing platform: the app reads facial expression locally, presents emotion-aware pet guidance and analytics, and can synchronize data or request AI support. The backend exposes chat, dashboard-insight, and support-content APIs; care coordination, music, widgets, and Wear OS extend the experience. Edges are limited to README statements and shown source/index references; several subsystems are represented by their exact directory where implementation was not sampled.

Main entry points: [`app/App.tsx`](https://github.com/endrigogustavo/mellowpet/blob/staging/app/App.tsx) (Mobile app), [`app/src/vision/VisionEngine.tsx`](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/VisionEngine.tsx) (Vision engine), [`app/src/state/AppContext.tsx`](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/state/AppContext.tsx) (App state), [`api/routers`](https://github.com/endrigogustavo/mellowpet/tree/staging/api/routers) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile wellbeing app"]
  node_app["Mobile app<br/>[App.tsx]"]
  node_appstate["App state<br/>[AppContext.tsx]"]
  node_emotiondata["Emotion guidance<br/>[emotions.ts]"]
  node_dashboard["Dashboard insights<br/>[dashboardClient.ts]"]
  node_checkins["Check-ins"]
  node_chatclient["Chat client<br/>[chatClient.ts]"]
end

subgraph group_vision["Local emotion sensing"]
  node_visionengine["Vision engine<br/>[VisionEngine.tsx]"]
  node_nativevision["Native camera reader"]
  node_classifier["Expression classifier"]
  node_calibration["Personal calibration"]
  node_visionevents["Vision event queue<br/>[eventQueue.ts]"]
end

subgraph group_backend["API and AI services"]
  node_api["FastAPI service<br/>[main.py]"]
  node_routes["API routes"]
  node_aiservice["AI provider service<br/>[ai_service.py]"]
  node_crisis["Crisis support<br/>[crisis.py]"]
  node_tools["Support content<br/>[tools.py]"]
end

subgraph group_care["Care and synchronization"]
  node_careclient["Care coordination<br/>[careClient.ts]"]
  node_supabase[("Supabase data and auth<br/>[client.ts]")]
  node_carepush["Care notifications<br/>[index.ts]"]
end

subgraph group_extensions["Connected experiences"]
  node_spotify["Music integration<br/>[spotifyClient.tsx]"]
  node_widgets["Android widgets<br/>[WidgetStore.kt]"]
  node_wear["Wear OS companion<br/>[MellowApp.kt]"]
end

node_user(("App user"))
node_ai_provider(("External AI providers"))

node_user -->|"uses"| node_app
node_app -->|"mounts"| node_appstate
node_appstate -->|"uses"| node_visionengine
node_visionengine -->|"requests frames"| node_nativevision
node_visionengine -->|"classifies frames"| node_classifier
node_visionengine -->|"loads and saves"| node_calibration
node_visionengine -->|"queues feedback"| node_visionevents
node_classifier -->|"uses emotion keys"| node_emotiondata
node_user -->|"records check-ins"| node_checkins
node_appstate -->|"uses guidance"| node_emotiondata
node_app -->|"shows analytics"| node_dashboard
node_dashboard -->|"requests insight"| node_api
node_app -->|"offers chat"| node_chatclient
node_chatclient -->|"sends chat requests"| node_api
node_api -->|"mounts routes"| node_routes
node_routes -->|"uses AI service"| node_aiservice
node_routes -->|"uses crisis support"| node_crisis
node_routes -->|"serves support content"| node_tools
node_aiservice -.->|"calls configured provider"| node_ai_provider
node_app -->|"offers care features"| node_careclient
node_careclient -->|"reads and writes"| node_supabase
node_appstate -->|"uses authentication"| node_supabase
node_carepush -.->|"sends care alerts"| node_user
node_app -->|"offers music"| node_spotify
node_spotify -.->|"reads stored playlists"| node_supabase
node_app -->|"supports widgets"| node_widgets
node_app -.->|"pairs with watch"| node_wear

click node_app "https://github.com/endrigogustavo/mellowpet/blob/staging/app/App.tsx"
click node_appstate "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/state/AppContext.tsx"
click node_emotiondata "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/data/emotions.ts"
click node_dashboard "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/dashboard/dashboardClient.ts"
click node_checkins "https://github.com/endrigogustavo/mellowpet/tree/staging/app/src/checkins"
click node_chatclient "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/chat/chatClient.ts"
click node_visionengine "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/VisionEngine.tsx"
click node_nativevision "https://github.com/endrigogustavo/mellowpet/blob/staging/app/modules/mellow-vision/android/src/main/java/com/mellowpet/vision/BackgroundReader.kt"
click node_classifier "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/expressionEngine.ts"
click node_calibration "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/personalCalibration.ts"
click node_visionevents "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/eventQueue.ts"
click node_api "https://github.com/endrigogustavo/mellowpet/blob/staging/api/main.py"
click node_routes "https://github.com/endrigogustavo/mellowpet/tree/staging/api/routers"
click node_aiservice "https://github.com/endrigogustavo/mellowpet/blob/staging/api/services/ai_service.py"
click node_crisis "https://github.com/endrigogustavo/mellowpet/blob/staging/api/services/crisis.py"
click node_tools "https://github.com/endrigogustavo/mellowpet/blob/staging/api/routers/tools.py"
click node_careclient "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/care/careClient.ts"
click node_supabase "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/supabase/client.ts"
click node_carepush "https://github.com/endrigogustavo/mellowpet/blob/staging/supabase/functions/care-push/index.ts"
click node_spotify "https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/spotify/spotifyClient.tsx"
click node_widgets "https://github.com/endrigogustavo/mellowpet/blob/staging/app/modules/mellow-widget/android/src/main/java/com/mellowpet/widget/WidgetStore.kt"
click node_wear "https://github.com/endrigogustavo/mellowpet/blob/staging/wear/app/src/main/java/com/mellowpet/wear/ui/MellowApp.kt"

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_app,node_appstate,node_emotiondata,node_dashboard,node_checkins,node_chatclient,node_user toneBlue
class node_visionengine,node_nativevision,node_classifier,node_calibration,node_visionevents toneAmber
class node_api,node_routes,node_aiservice,node_crisis,node_tools toneMint
class node_careclient,node_supabase,node_carepush toneRose
class node_spotify,node_widgets,node_wear,node_ai_provider toneIndigo
```

## Components

### Mobile wellbeing app

- [Mobile app](https://github.com/endrigogustavo/mellowpet/blob/staging/app/App.tsx): `app/App.tsx`
- [App state](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/state/AppContext.tsx): `app/src/state/AppContext.tsx`
- [Emotion guidance](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/data/emotions.ts): `app/src/data/emotions.ts`
- [Dashboard insights](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/dashboard/dashboardClient.ts): `app/src/dashboard/dashboardClient.ts`
- [Check-ins](https://github.com/endrigogustavo/mellowpet/tree/staging/app/src/checkins): `app/src/checkins`
- [Chat client](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/chat/chatClient.ts): `app/src/chat/chatClient.ts`

### Local emotion sensing

- [Vision engine](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/VisionEngine.tsx): `app/src/vision/VisionEngine.tsx`
- [Native camera reader](https://github.com/endrigogustavo/mellowpet/blob/staging/app/modules/mellow-vision/android/src/main/java/com/mellowpet/vision/BackgroundReader.kt): `app/modules/mellow-vision/android/src/main/java/com/mellowpet/vision/BackgroundReader.kt`
- [Expression classifier](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/expressionEngine.ts): `app/src/vision/expressionEngine.ts`
- [Personal calibration](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/personalCalibration.ts): `app/src/vision/personalCalibration.ts`
- [Vision event queue](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/vision/eventQueue.ts): `app/src/vision/eventQueue.ts`

### API and AI services

- [FastAPI service](https://github.com/endrigogustavo/mellowpet/blob/staging/api/main.py): `api/main.py`
- [API routes](https://github.com/endrigogustavo/mellowpet/tree/staging/api/routers): `api/routers`
- [AI provider service](https://github.com/endrigogustavo/mellowpet/blob/staging/api/services/ai_service.py): `api/services/ai_service.py`
- [Crisis support](https://github.com/endrigogustavo/mellowpet/blob/staging/api/services/crisis.py): `api/services/crisis.py`
- [Support content](https://github.com/endrigogustavo/mellowpet/blob/staging/api/routers/tools.py): `api/routers/tools.py`

### Care and synchronization

- [Care coordination](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/care/careClient.ts): `app/src/care/careClient.ts`
- [Supabase data and auth](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/supabase/client.ts): `app/src/supabase/client.ts`
- [Care notifications](https://github.com/endrigogustavo/mellowpet/blob/staging/supabase/functions/care-push/index.ts): `supabase/functions/care-push/index.ts`

### Connected experiences

- [Music integration](https://github.com/endrigogustavo/mellowpet/blob/staging/app/src/spotify/spotifyClient.tsx): `app/src/spotify/spotifyClient.tsx`
- [Android widgets](https://github.com/endrigogustavo/mellowpet/blob/staging/app/modules/mellow-widget/android/src/main/java/com/mellowpet/widget/WidgetStore.kt): `app/modules/mellow-widget/android/src/main/java/com/mellowpet/widget/WidgetStore.kt`
- [Wear OS companion](https://github.com/endrigogustavo/mellowpet/blob/staging/wear/app/src/main/java/com/mellowpet/wear/ui/MellowApp.kt): `wear/app/src/main/java/com/mellowpet/wear/ui/MellowApp.kt`

### Other components

- **App user**
- **External AI providers**

## Connections

- App user → Mobile app: uses (evidence: `README.md`)
- Mobile app → App state: mounts (evidence: `app/App.tsx`)
- App state → Vision engine: uses (evidence: `app/src/state/AppContext.tsx`)
- Vision engine → Native camera reader: requests frames (evidence: `app/src/vision/VisionEngine.tsx`)
- Vision engine → Expression classifier: classifies frames (evidence: `app/src/vision/VisionEngine.tsx`)
- Vision engine → Personal calibration: loads and saves (evidence: `app/src/vision/VisionEngine.tsx`)
- Vision engine → Vision event queue: queues feedback (evidence: `app/src/vision/VisionEngine.tsx`)
- Expression classifier → Emotion guidance: uses emotion keys (evidence: `app/src/vision/expressionEngine.ts`)
- App user → Check-ins: records check-ins (evidence: `README.md`)
- App state → Emotion guidance: uses guidance (evidence: `app/src/state/AppContext.tsx`)
- Mobile app → Dashboard insights: shows analytics (evidence: `README.md`)
- Dashboard insights → FastAPI service: requests insight (evidence: `README.md`)
- Mobile app → Chat client: offers chat (evidence: `README.md`)
- Chat client → FastAPI service: sends chat requests (evidence: `README.md`)
- FastAPI service → API routes: mounts routes (evidence: `api/main.py`)
- API routes → AI provider service: uses AI service (evidence: `api/routers/ai_chat.py`)
- API routes → Crisis support: uses crisis support (evidence: `api/routers/ai_chat.py`)
- API routes → Support content: serves support content (evidence: `README.md`)
- AI provider service → External AI providers: calls configured provider (evidence: `README.md`)
- Mobile app → Care coordination: offers care features (evidence: `README.md`)
- Care coordination → Supabase data and auth: reads and writes (evidence: `app/src/care/careClient.ts`)
- App state → Supabase data and auth: uses authentication (evidence: `app/src/state/AppContext.tsx`)
- Care notifications → App user: sends care alerts
- Mobile app → Music integration: offers music (evidence: `app/App.tsx`)
- Music integration → Supabase data and auth: reads stored playlists
- Mobile app → Android widgets: supports widgets (evidence: `README.md`)
- Mobile app → Wear OS companion: pairs with watch (evidence: `README.md`)