# fortunatoman/goodie-ai architecture

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

- Interactive diagram: https://gitdiagram.com/fortunatoman/goodie-ai
- Repository: https://github.com/fortunatoman/goodie-ai

## Overview

Goodie AI is a full-stack character-chat product: users discover or create characters, chat with them, collect conversations, generate images, and use AI calls. The React app presents these flows; its services and hooks manage client state and API interactions, while Express controllers delegate domain work to services backed by Supabase and AI providers. The README documents Supabase and OpenAI/DeepAI integrations. Some frontend-to-backend wiring and unsampled feature internals are not shown, so those links are omitted or marked unverified.

Main entry points: [`Frontend/src/App.tsx`](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/App.tsx) (App routing), [`Backend/src/services/call.service.ts`](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/call.service.ts) (Call service), [`Backend/src/services/message.service.ts`](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/message.service.ts) (Message service), [`Frontend/src/hooks/useChats.ts`](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/hooks/useChats.ts) (Chats hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_discover["Discover<br/>[index.tsx]"]
  node_create["Create character<br/>[index.tsx]"]
  node_chat["Chat<br/>[index.tsx]"]
  node_collection["Collection<br/>[index.tsx]"]
  node_image["Image generation<br/>[index.tsx]"]
  node_myai["My AI<br/>[index.tsx]"]
  node_subscriptions["Subscriptions<br/>[index.tsx]"]
end

subgraph group_client["Client state and API"]
  node_global["Global context<br/>[GlobalContext.tsx]"]
  node_authhook["Auth hook<br/>[useAuth.ts]"]
  node_authclient["Auth service<br/>[auth.service.ts]"]
  node_chatshook["Chats hook<br/>[useChats.ts]"]
  node_chatsclient["Chats service<br/>[chats.service.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["Express API<br/>[index.ts]"]
  node_authctrl["Auth controller<br/>[auth.controller.ts]"]
  node_callctrl["Call controller<br/>[call.controller.ts]"]
  node_messagectrl["Message controller"]
end

subgraph group_domain["Domain services"]
  node_authsvc["Auth service<br/>[auth.service.ts]"]
  node_callsvc["Call service<br/>[call.service.ts]"]
  node_charactersvc["Character service"]
  node_chatssvc["Chats service<br/>[chats.service.ts]"]
  node_messagesvc["Message service<br/>[message.service.ts]"]
end

node_user(("User"))
node_supabase[("Supabase")]
node_openai["OpenAI"]
node_deepai["DeepAI"]

node_user -->|"uses"| node_app
node_app -->|"provides state"| node_global
node_app -->|"routes to"| node_discover
node_app -->|"routes to"| node_create
node_app -->|"routes to"| node_chat
node_app -->|"routes to"| node_collection
node_app -->|"routes to"| node_image
node_app -->|"routes to"| node_myai
node_app -->|"routes to"| node_subscriptions
node_authhook -->|"reads state"| node_global
node_authhook -->|"delegates"| node_authclient
node_authclient -.->|"calls API"| node_authctrl
node_chat -->|"uses"| node_chatshook
node_collection -->|"uses"| node_chatshook
node_myai -->|"uses"| node_chatshook
node_chatshook -->|"delegates"| node_chatsclient
node_chatsclient -.->|"calls API"| node_chatssvc
node_backend -.->|"routes requests"| node_authctrl
node_authctrl -->|"delegates"| node_authsvc
node_callctrl -->|"delegates"| node_callsvc
node_messagectrl -->|"delegates"| node_messagesvc
node_messagectrl -->|"loads character"| node_charactersvc
node_authsvc -->|"auth operations"| node_supabase
node_callsvc -->|"reads and writes"| node_supabase
node_charactersvc -->|"reads and writes"| node_supabase
node_chatssvc -->|"reads and writes"| node_supabase
node_messagesvc -->|"reads and writes"| node_supabase
node_callsvc -->|"loads character"| node_charactersvc
node_callsvc -->|"creates message"| node_messagesvc
node_callsvc -->|"generates voice"| node_openai
node_messagesvc -.->|"AI generation"| node_openai
node_messagesvc -.->|"image generation"| node_deepai

click node_app "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/App.tsx"
click node_discover "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Discover/index.tsx"
click node_create "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/CreateCharacter/index.tsx"
click node_chat "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Chat/index.tsx"
click node_collection "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Collection/index.tsx"
click node_image "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/GenerateImage/index.tsx"
click node_myai "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/MyAI/index.tsx"
click node_subscriptions "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/subscriptions/index.tsx"
click node_global "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/contexts/GlobalContext.tsx"
click node_authhook "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/hooks/useAuth.ts"
click node_authclient "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/services/auth.service.ts"
click node_chatshook "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/hooks/useChats.ts"
click node_chatsclient "https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/services/chats.service.ts"
click node_backend "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/index.ts"
click node_authctrl "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/auth.controller.ts"
click node_callctrl "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/call.controller.ts"
click node_messagectrl "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/message.controller.ts"
click node_authsvc "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/auth.service.ts"
click node_callsvc "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/call.service.ts"
click node_charactersvc "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/character.service.ts"
click node_chatssvc "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/chats.service.ts"
click node_messagesvc "https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/message.service.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_discover,node_create,node_chat,node_collection,node_image,node_myai,node_subscriptions,node_user toneBlue
class node_global,node_authhook,node_authclient,node_chatshook,node_chatsclient,node_supabase toneAmber
class node_backend,node_authctrl,node_callctrl,node_messagectrl toneMint
class node_authsvc,node_callsvc,node_charactersvc,node_chatssvc,node_messagesvc toneRose
class node_openai,node_deepai toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/App.tsx): `Frontend/src/App.tsx`
- [Discover](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Discover/index.tsx): `Frontend/src/pages/Discover/index.tsx`
- [Create character](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/CreateCharacter/index.tsx): `Frontend/src/pages/CreateCharacter/index.tsx`
- [Chat](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Chat/index.tsx): `Frontend/src/pages/Chat/index.tsx`
- [Collection](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/Collection/index.tsx): `Frontend/src/pages/Collection/index.tsx`
- [Image generation](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/GenerateImage/index.tsx): `Frontend/src/pages/GenerateImage/index.tsx`
- [My AI](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/MyAI/index.tsx): `Frontend/src/pages/MyAI/index.tsx`
- [Subscriptions](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/pages/subscriptions/index.tsx): `Frontend/src/pages/subscriptions/index.tsx`

### Client state and API

- [Global context](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/contexts/GlobalContext.tsx): `Frontend/src/contexts/GlobalContext.tsx`
- [Auth hook](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/hooks/useAuth.ts): `Frontend/src/hooks/useAuth.ts`
- [Auth service](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/services/auth.service.ts): `Frontend/src/services/auth.service.ts`
- [Chats hook](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/hooks/useChats.ts): `Frontend/src/hooks/useChats.ts`
- [Chats service](https://github.com/fortunatoman/goodie-ai/blob/master/Frontend/src/services/chats.service.ts): `Frontend/src/services/chats.service.ts`

### Backend API

- [Express API](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/index.ts): `Backend/src/index.ts`
- [Auth controller](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/auth.controller.ts): `Backend/src/controllers/auth.controller.ts`
- [Call controller](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/call.controller.ts): `Backend/src/controllers/call.controller.ts`
- [Message controller](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/controllers/message.controller.ts): `Backend/src/controllers/message.controller.ts`

### Domain services

- [Auth service](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/auth.service.ts): `Backend/src/services/auth.service.ts`
- [Call service](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/call.service.ts): `Backend/src/services/call.service.ts`
- [Character service](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/character.service.ts): `Backend/src/services/character.service.ts`
- [Chats service](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/chats.service.ts): `Backend/src/services/chats.service.ts`
- [Message service](https://github.com/fortunatoman/goodie-ai/blob/master/Backend/src/services/message.service.ts): `Backend/src/services/message.service.ts`

### Other components

- **User**
- **Supabase**
- **OpenAI**
- **DeepAI**

## Connections

- User → App routing: uses (evidence: `Frontend/src/App.tsx`)
- App routing → Global context: provides state (evidence: `Frontend/src/App.tsx`)
- App routing → Discover: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → Create character: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → Chat: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → Collection: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → Image generation: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → My AI: routes to (evidence: `Frontend/src/App.tsx`)
- App routing → Subscriptions: routes to (evidence: `Frontend/src/App.tsx`)
- Auth hook → Global context: reads state (evidence: `Frontend/src/hooks/useAuth.ts`)
- Auth hook → Auth service: delegates (evidence: `Frontend/src/hooks/useAuth.ts`)
- Auth service → Auth controller: calls API
- Chat → Chats hook: uses (evidence: `Frontend/src/pages/Chat/index.tsx`)
- Collection → Chats hook: uses (evidence: `Frontend/src/pages/Collection/index.tsx`)
- My AI → Chats hook: uses (evidence: `Frontend/src/pages/MyAI/index.tsx`)
- Chats hook → Chats service: delegates (evidence: `Frontend/src/hooks/useChats.ts`)
- Chats service → Chats service: calls API
- Express API → Auth controller: routes requests
- Auth controller → Auth service: delegates (evidence: `Backend/src/controllers/auth.controller.ts`)
- Call controller → Call service: delegates (evidence: `Backend/src/controllers/call.controller.ts`)
- Message controller → Message service: delegates (evidence: `Backend/src/controllers/message.controller.ts`)
- Message controller → Character service: loads character (evidence: `Backend/src/controllers/message.controller.ts`)
- Auth service → Supabase: auth operations (evidence: `Backend/src/services/auth.service.ts`)
- Call service → Supabase: reads and writes (evidence: `Backend/src/services/call.service.ts`)
- Character service → Supabase: reads and writes (evidence: `Backend/src/services/character.service.ts`)
- Chats service → Supabase: reads and writes (evidence: `Backend/src/services/chats.service.ts`)
- Message service → Supabase: reads and writes (evidence: `Backend/src/services/message.service.ts`)
- Call service → Character service: loads character (evidence: `Backend/src/services/call.service.ts`)
- Call service → Message service: creates message (evidence: `Backend/src/services/call.service.ts`)
- Call service → OpenAI: generates voice (evidence: `Backend/src/services/call.service.ts`)
- Message service → OpenAI: AI generation
- Message service → DeepAI: image generation
