# harry-jees/teddy-bud architecture

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

- Interactive diagram: https://gitdiagram.com/harry-jees/teddy-bud
- Repository: https://github.com/harry-jees/teddy-bud

## Overview

Teddy Bud is a local-first AI companion app for conversation and personal reflection, with Android and desktop distribution. The user enters through the app shell, signs in or completes onboarding as needed, then chats or uses Discover’s reflection and wellbeing features; local personal data is stored on-device, while authenticated AI and account requests go through the gateway. The graph preserves documented capabilities even where implementation details were not sampled; links without direct source evidence are omitted.

Main entry points: [`client/App.tsx`](https://github.com/harry-jees/teddy-bud/blob/main/client/App.tsx) (App shell), [`client/src/services/localData.ts`](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/localData.ts) (Local personal data), [`client/src/screens/WellbeingScreens.tsx`](https://github.com/harry-jees/teddy-bud/blob/main/client/src/screens/WellbeingScreens.tsx) (Reflection and wellbeing), [`gateway-worker/src/index.mjs`](https://github.com/harry-jees/teddy-bud/blob/main/gateway-worker/src/index.mjs) (Gateway service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_chat["Conversation<br/>[App.tsx]"]
  node_onboarding["Onboarding and consent"]
  node_wellbeing["Reflection and wellbeing"]
  node_wellbeing_studio["Guided exercises"]
  node_characters["Assistant characters<br/>[characters.ts]"]
end

subgraph group_personal["Personal data"]
  node_local_data["Local personal data<br/>[localData.ts]"]
  node_local_store[("Platform storage<br/>[localStore.ts]")]
  node_backup["Encrypted backup<br/>[backup.ts]"]
  node_backup_files["Backup file handling<br/>[backupFiles.ts]"]
end

subgraph group_services["Account and AI services"]
  node_login_ui["Account screen"]
  node_auth["Account authentication<br/>[browserAuth.ts]"]
  node_gateway_client["AI gateway client<br/>[gateway.ts]"]
  node_gateway_worker["Gateway service<br/>[index.mjs]"]
end

subgraph group_presentation["Shared interface"]
  node_chat_presentation["Chat presentation"]
  node_shared_styles["Shared styles<br/>[appStyles.ts]"]
end

node_user(("User"))
node_remote_services["Account and AI providers"]

node_user -->|"uses"| node_app
node_app -->|"presents"| node_onboarding
node_app -->|"hosts"| node_chat
node_app -->|"hosts"| node_wellbeing
node_app -->|"offers"| node_wellbeing_studio
node_app -->|"reads and writes"| node_local_data
node_app -->|"requests replies"| node_gateway_client
node_app -->|"presents"| node_login_ui
node_login_ui -->|"uses"| node_auth
node_auth -->|"sends account requests"| node_gateway_worker
node_gateway_client -->|"sends AI requests"| node_gateway_worker
node_gateway_worker -->|"forwards requests"| node_remote_services
node_local_data -->|"persists data"| node_local_store
node_local_data -->|"uses character definitions"| node_characters
node_backup -->|"exports and imports"| node_local_data
node_app -->|"handles backup import"| node_backup
node_wellbeing -->|"reads and writes entries"| node_local_data
node_wellbeing -->|"exports journal text"| node_backup_files
node_app -->|"renders"| node_chat_presentation
node_chat_presentation -->|"uses"| node_shared_styles

click node_app "https://github.com/harry-jees/teddy-bud/blob/main/client/App.tsx"
click node_chat "https://github.com/harry-jees/teddy-bud/blob/main/client/App.tsx"
click node_onboarding "https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/OnboardingConsent.tsx"
click node_wellbeing "https://github.com/harry-jees/teddy-bud/blob/main/client/src/screens/WellbeingScreens.tsx"
click node_wellbeing_studio "https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/WellbeingStudio.tsx"
click node_characters "https://github.com/harry-jees/teddy-bud/blob/main/client/src/characters.ts"
click node_local_data "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/localData.ts"
click node_local_store "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/localStore.ts"
click node_backup "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/backup.ts"
click node_backup_files "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/backupFiles.ts"
click node_login_ui "https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/BrowserLoginScreen.tsx"
click node_auth "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/browserAuth.ts"
click node_gateway_client "https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/gateway.ts"
click node_gateway_worker "https://github.com/harry-jees/teddy-bud/blob/main/gateway-worker/src/index.mjs"
click node_chat_presentation "https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/ChatPresentation.tsx"
click node_shared_styles "https://github.com/harry-jees/teddy-bud/blob/main/client/src/theme/appStyles.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_app,node_chat,node_onboarding,node_wellbeing,node_wellbeing_studio,node_characters,node_user toneBlue
class node_local_data,node_local_store,node_backup,node_backup_files toneAmber
class node_login_ui,node_auth,node_gateway_client,node_gateway_worker toneMint
class node_chat_presentation,node_shared_styles toneRose
class node_remote_services toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/harry-jees/teddy-bud/blob/main/client/App.tsx): `client/App.tsx`
- [Conversation](https://github.com/harry-jees/teddy-bud/blob/main/client/App.tsx): `client/App.tsx`
- [Onboarding and consent](https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/OnboardingConsent.tsx): `client/src/components/OnboardingConsent.tsx`
- [Reflection and wellbeing](https://github.com/harry-jees/teddy-bud/blob/main/client/src/screens/WellbeingScreens.tsx): `client/src/screens/WellbeingScreens.tsx`
- [Guided exercises](https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/WellbeingStudio.tsx): `client/src/components/WellbeingStudio.tsx`
- [Assistant characters](https://github.com/harry-jees/teddy-bud/blob/main/client/src/characters.ts): `client/src/characters.ts`

### Personal data

- [Local personal data](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/localData.ts): `client/src/services/localData.ts`
- [Platform storage](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/localStore.ts): `client/src/services/localStore.ts`
- [Encrypted backup](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/backup.ts): `client/src/services/backup.ts`
- [Backup file handling](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/backupFiles.ts): `client/src/services/backupFiles.ts`

### Account and AI services

- [Account screen](https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/BrowserLoginScreen.tsx): `client/src/components/BrowserLoginScreen.tsx`
- [Account authentication](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/browserAuth.ts): `client/src/services/browserAuth.ts`
- [AI gateway client](https://github.com/harry-jees/teddy-bud/blob/main/client/src/services/gateway.ts): `client/src/services/gateway.ts`
- [Gateway service](https://github.com/harry-jees/teddy-bud/blob/main/gateway-worker/src/index.mjs): `gateway-worker/src/index.mjs`

### Shared interface

- [Chat presentation](https://github.com/harry-jees/teddy-bud/blob/main/client/src/components/ChatPresentation.tsx): `client/src/components/ChatPresentation.tsx`
- [Shared styles](https://github.com/harry-jees/teddy-bud/blob/main/client/src/theme/appStyles.ts): `client/src/theme/appStyles.ts`

### Other components

- **User**
- **Account and AI providers**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Onboarding and consent: presents (evidence: `client/App.tsx`)
- App shell → Conversation: hosts (evidence: `README.md`)
- App shell → Reflection and wellbeing: hosts (evidence: `README.md`)
- App shell → Guided exercises: offers (evidence: `README.md`)
- App shell → Local personal data: reads and writes (evidence: `client/App.tsx`)
- App shell → AI gateway client: requests replies (evidence: `client/App.tsx`)
- App shell → Account screen: presents (evidence: `client/App.tsx`)
- Account screen → Account authentication: uses (evidence: `client/src/components/BrowserLoginScreen.tsx`)
- Account authentication → Gateway service: sends account requests (evidence: `client/src/services/browserAuth.ts`)
- AI gateway client → Gateway service: sends AI requests (evidence: `README.md`)
- Gateway service → Account and AI providers: forwards requests (evidence: `README.md`)
- Local personal data → Platform storage: persists data (evidence: `client/src/services/localData.ts`)
- Local personal data → Assistant characters: uses character definitions (evidence: `client/src/services/localData.ts`)
- Encrypted backup → Local personal data: exports and imports (evidence: `client/src/services/backup.ts`)
- App shell → Encrypted backup: handles backup import (evidence: `client/App.tsx`)
- Reflection and wellbeing → Local personal data: reads and writes entries (evidence: `client/src/screens/WellbeingScreens.tsx`)
- Reflection and wellbeing → Backup file handling: exports journal text (evidence: `client/src/screens/WellbeingScreens.tsx`)
- App shell → Chat presentation: renders (evidence: `client/App.tsx`)
- Chat presentation → Shared styles: uses (evidence: `client/src/components/ChatPresentation.tsx`)
