# kinghochin/family-chat architecture

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

- Interactive diagram: https://gitdiagram.com/kinghochin/family-chat
- Repository: https://github.com/kinghochin/family-chat

## Overview

Gatherly is a shared family research organiser: members sign in, capture messages and attachments, organise ideas into topics, and can request Hermes-assisted suggestions or reusable AI artifacts. The app also supports household and member management. The separate trip-board route demonstrates local-only drag-and-drop organisation. Edges reflect the README and indexed imports/calls; unsampled implementation details are not inferred.

Main entry points: [`src/lib/supabase/server.ts`](https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/server.ts) (Server Supabase client), [`src/app/api/messages/route.ts`](https://github.com/kinghochin/family-chat/blob/main/src/app/api/messages/route.ts) (Message capture API), [`src/app/api/topics/[topicId]/selection-requests/[requestId]/confirm/route.ts`](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/selection-requests/%5BrequestId%5D/confirm/route.ts) (Suggestion confirmation), [`src/app/api/topics/[topicId]/ai-requests/route.ts`](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/ai-requests/route.ts) (AI request API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Member experience"]
  node_family_shell["Family workspace shell<br/>[family-shell.tsx]"]
  node_trip_board["Local trip board<br/>[trip-board.tsx]"]
end

subgraph group_research["Research workflow"]
  node_inbox_page["Inbox page<br/>[page.tsx]"]
  node_inbox_ui["Inbox interactions"]
  node_message_api["Message capture API<br/>[route.ts]"]
  node_attachments["Attachment parsing"]
  node_topics_page["Topics page<br/>[page.tsx]"]
  node_topic_create["Topic creation form"]
  node_topics_api["Topic creation API<br/>[route.ts]"]
  node_topic_detail["Topic details<br/>[page.tsx]"]
end

subgraph group_assist["Assisted outputs"]
  node_selection_ui["Message suggestions"]
  node_selection_api["Selection requests<br/>[route.ts]"]
  node_selection_confirm["Suggestion confirmation<br/>[route.ts]"]
  node_topic_assistant["Topic AI assistant"]
  node_ai_requests["AI request API<br/>[route.ts]"]
  node_ai_callback["AI callback<br/>[route.ts]"]
  node_artifacts_pages["Artifact library<br/>[page.tsx]"]
  node_hermes["Hermes webhook"]
end

subgraph group_identity["Identity and household"]
  node_auth_pages["Sign-in pages<br/>[page.tsx]"]
  node_auth_form["Authentication form<br/>[auth-form.tsx]"]
  node_auth_actions["Sign-in actions<br/>[auth-actions.ts]"]
  node_member_settings["Member management<br/>[member-actions.ts]"]
end

subgraph group_platform["Data access"]
  node_server_client["Server Supabase client<br/>[server.ts]"]
  node_browser_client["Browser Supabase client<br/>[client.ts]"]
  node_admin_client["Admin Supabase client<br/>[admin.ts]"]
  node_supabase[("Supabase")]
end

node_member(("Family member"))

node_member -->|"opens"| node_auth_pages
node_auth_pages -->|"renders"| node_auth_form
node_auth_form -->|"submits"| node_auth_actions
node_auth_actions -->|"uses"| node_server_client
node_member -->|"opens"| node_inbox_page
node_inbox_page -->|"renders"| node_family_shell
node_inbox_page -->|"renders"| node_inbox_ui
node_inbox_ui -.->|"submits"| node_message_api
node_message_api -->|"uses"| node_server_client
node_message_api -->|"parses"| node_attachments
node_message_api -->|"stores messages"| node_supabase
node_member -->|"opens"| node_topics_page
node_topics_page -->|"renders"| node_topic_create
node_topic_create -.->|"creates topic"| node_topics_api
node_topics_api -->|"uses"| node_server_client
node_topics_api -->|"stores topic"| node_supabase
node_member -->|"opens"| node_topic_detail
node_topic_detail -->|"renders"| node_selection_ui
node_selection_ui -.->|"requests suggestions"| node_selection_api
node_selection_api -->|"sends candidates"| node_hermes
node_hermes -->|"returns suggestions"| node_selection_confirm
node_selection_confirm -->|"uses"| node_admin_client
node_selection_confirm -->|"authenticates user"| node_server_client
node_selection_confirm -->|"confirms records"| node_supabase
node_topic_detail -->|"renders"| node_topic_assistant
node_topic_assistant -.->|"submits prompt"| node_ai_requests
node_ai_requests -->|"uses"| node_server_client
node_ai_requests -->|"stores request"| node_supabase
node_ai_requests -->|"dispatches request"| node_hermes
node_hermes -->|"posts result"| node_ai_callback
node_ai_callback -->|"uses"| node_admin_client
node_ai_callback -->|"stores results"| node_supabase
node_artifacts_pages -->|"renders"| node_family_shell
node_member -.->|"manages household"| node_member_settings
node_member_settings -->|"uses"| node_server_client
node_trip_board -.->|"organises demo ideas"| node_member
node_family_shell -->|"loads household data"| node_server_client
node_server_client -->|"accesses"| node_supabase
node_browser_client -.->|"accesses"| node_supabase

click node_auth_pages "https://github.com/kinghochin/family-chat/blob/main/src/app/login/page.tsx"
click node_auth_form "https://github.com/kinghochin/family-chat/blob/main/src/components/auth-form.tsx"
click node_auth_actions "https://github.com/kinghochin/family-chat/blob/main/src/app/auth-actions.ts"
click node_family_shell "https://github.com/kinghochin/family-chat/blob/main/src/components/family-shell.tsx"
click node_inbox_page "https://github.com/kinghochin/family-chat/blob/main/src/app/inbox/page.tsx"
click node_inbox_ui "https://github.com/kinghochin/family-chat/blob/main/src/components/inbox-interactive.tsx"
click node_message_api "https://github.com/kinghochin/family-chat/blob/main/src/app/api/messages/route.ts"
click node_attachments "https://github.com/kinghochin/family-chat/blob/main/src/lib/message-attachments.ts"
click node_topics_page "https://github.com/kinghochin/family-chat/blob/main/src/app/topics/page.tsx"
click node_topic_create "https://github.com/kinghochin/family-chat/blob/main/src/components/topic-create-form.tsx"
click node_topics_api "https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/route.ts"
click node_topic_detail "https://github.com/kinghochin/family-chat/blob/main/src/app/topics/%5BtopicId%5D/page.tsx"
click node_selection_ui "https://github.com/kinghochin/family-chat/blob/main/src/components/topic-selection-panel.tsx"
click node_selection_api "https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/selection-requests/route.ts"
click node_selection_confirm "https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/selection-requests/%5BrequestId%5D/confirm/route.ts"
click node_topic_assistant "https://github.com/kinghochin/family-chat/blob/main/src/components/topic-assistant.tsx"
click node_ai_requests "https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/ai-requests/route.ts"
click node_ai_callback "https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/ai-callback/route.ts"
click node_artifacts_pages "https://github.com/kinghochin/family-chat/blob/main/src/app/artifacts/page.tsx"
click node_member_settings "https://github.com/kinghochin/family-chat/blob/main/src/app/settings/member-actions.ts"
click node_trip_board "https://github.com/kinghochin/family-chat/blob/main/src/components/trip-board.tsx"
click node_server_client "https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/server.ts"
click node_browser_client "https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/client.ts"
click node_admin_client "https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/admin.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_family_shell,node_trip_board toneBlue
class node_inbox_page,node_inbox_ui,node_message_api,node_attachments,node_topics_page,node_topic_create,node_topics_api,node_topic_detail toneAmber
class node_selection_ui,node_selection_api,node_selection_confirm,node_topic_assistant,node_ai_requests,node_ai_callback,node_artifacts_pages,node_hermes toneMint
class node_auth_pages,node_auth_form,node_auth_actions,node_member_settings toneRose
class node_server_client,node_browser_client,node_admin_client,node_supabase,node_member toneIndigo
```

## Components

### Member experience

- [Family workspace shell](https://github.com/kinghochin/family-chat/blob/main/src/components/family-shell.tsx): `src/components/family-shell.tsx`
- [Local trip board](https://github.com/kinghochin/family-chat/blob/main/src/components/trip-board.tsx): `src/components/trip-board.tsx`

### Research workflow

- [Inbox page](https://github.com/kinghochin/family-chat/blob/main/src/app/inbox/page.tsx): `src/app/inbox/page.tsx`
- [Inbox interactions](https://github.com/kinghochin/family-chat/blob/main/src/components/inbox-interactive.tsx): `src/components/inbox-interactive.tsx`
- [Message capture API](https://github.com/kinghochin/family-chat/blob/main/src/app/api/messages/route.ts): `src/app/api/messages/route.ts`
- [Attachment parsing](https://github.com/kinghochin/family-chat/blob/main/src/lib/message-attachments.ts): `src/lib/message-attachments.ts`
- [Topics page](https://github.com/kinghochin/family-chat/blob/main/src/app/topics/page.tsx): `src/app/topics/page.tsx`
- [Topic creation form](https://github.com/kinghochin/family-chat/blob/main/src/components/topic-create-form.tsx): `src/components/topic-create-form.tsx`
- [Topic creation API](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/route.ts): `src/app/api/topics/route.ts`
- [Topic details](https://github.com/kinghochin/family-chat/blob/main/src/app/topics/%5BtopicId%5D/page.tsx): `src/app/topics/[topicId]/page.tsx`

### Assisted outputs

- [Message suggestions](https://github.com/kinghochin/family-chat/blob/main/src/components/topic-selection-panel.tsx): `src/components/topic-selection-panel.tsx`
- [Selection requests](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/selection-requests/route.ts): `src/app/api/topics/[topicId]/selection-requests/route.ts`
- [Suggestion confirmation](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/selection-requests/%5BrequestId%5D/confirm/route.ts): `src/app/api/topics/[topicId]/selection-requests/[requestId]/confirm/route.ts`
- [Topic AI assistant](https://github.com/kinghochin/family-chat/blob/main/src/components/topic-assistant.tsx): `src/components/topic-assistant.tsx`
- [AI request API](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/ai-requests/route.ts): `src/app/api/topics/[topicId]/ai-requests/route.ts`
- [AI callback](https://github.com/kinghochin/family-chat/blob/main/src/app/api/topics/%5BtopicId%5D/ai-callback/route.ts): `src/app/api/topics/[topicId]/ai-callback/route.ts`
- [Artifact library](https://github.com/kinghochin/family-chat/blob/main/src/app/artifacts/page.tsx): `src/app/artifacts/page.tsx`
- **Hermes webhook**

### Identity and household

- [Sign-in pages](https://github.com/kinghochin/family-chat/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [Authentication form](https://github.com/kinghochin/family-chat/blob/main/src/components/auth-form.tsx): `src/components/auth-form.tsx`
- [Sign-in actions](https://github.com/kinghochin/family-chat/blob/main/src/app/auth-actions.ts): `src/app/auth-actions.ts`
- [Member management](https://github.com/kinghochin/family-chat/blob/main/src/app/settings/member-actions.ts): `src/app/settings/member-actions.ts`

### Data access

- [Server Supabase client](https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Browser Supabase client](https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/client.ts): `src/lib/supabase/client.ts`
- [Admin Supabase client](https://github.com/kinghochin/family-chat/blob/main/src/lib/supabase/admin.ts): `src/lib/supabase/admin.ts`
- **Supabase**

### Other components

- **Family member**

## Connections

- Family member → Sign-in pages: opens
- Sign-in pages → Authentication form: renders (evidence: `src/app/login/page.tsx`)
- Authentication form → Sign-in actions: submits (evidence: `src/components/auth-form.tsx`)
- Sign-in actions → Server Supabase client: uses (evidence: `src/app/auth-actions.ts`)
- Family member → Inbox page: opens
- Inbox page → Family workspace shell: renders (evidence: `src/app/inbox/page.tsx`)
- Inbox page → Inbox interactions: renders (evidence: `src/app/inbox/page.tsx`)
- Inbox interactions → Message capture API: submits
- Message capture API → Server Supabase client: uses (evidence: `src/app/api/messages/route.ts`)
- Message capture API → Attachment parsing: parses (evidence: `src/app/api/messages/route.ts`)
- Message capture API → Supabase: stores messages (evidence: `src/app/api/messages/route.ts`)
- Family member → Topics page: opens
- Topics page → Topic creation form: renders (evidence: `src/app/topics/page.tsx`)
- Topic creation form → Topic creation API: creates topic
- Topic creation API → Server Supabase client: uses (evidence: `src/app/api/topics/route.ts`)
- Topic creation API → Supabase: stores topic (evidence: `src/app/api/topics/route.ts`)
- Family member → Topic details: opens
- Topic details → Message suggestions: renders (evidence: `src/app/topics/[topicId]/page.tsx`)
- Message suggestions → Selection requests: requests suggestions
- Selection requests → Hermes webhook: sends candidates
- Hermes webhook → Suggestion confirmation: returns suggestions
- Suggestion confirmation → Admin Supabase client: uses (evidence: `src/app/api/topics/[topicId]/selection-requests/[requestId]/confirm/route.ts`)
- Suggestion confirmation → Server Supabase client: authenticates user (evidence: `src/app/api/topics/[topicId]/selection-requests/[requestId]/confirm/route.ts`)
- Suggestion confirmation → Supabase: confirms records
- Topic details → Topic AI assistant: renders (evidence: `src/app/topics/[topicId]/page.tsx`)
- Topic AI assistant → AI request API: submits prompt
- AI request API → Server Supabase client: uses (evidence: `src/app/api/topics/[topicId]/ai-requests/route.ts`)
- AI request API → Supabase: stores request (evidence: `src/app/api/topics/[topicId]/ai-requests/route.ts`)
- AI request API → Hermes webhook: dispatches request (evidence: `src/app/api/topics/[topicId]/ai-requests/route.ts`)
- Hermes webhook → AI callback: posts result
- AI callback → Admin Supabase client: uses (evidence: `src/app/api/topics/[topicId]/ai-callback/route.ts`)
- AI callback → Supabase: stores results (evidence: `src/app/api/topics/[topicId]/ai-callback/route.ts`)
- Artifact library → Family workspace shell: renders (evidence: `src/app/artifacts/page.tsx`)
- Family member → Member management: manages household
- Member management → Server Supabase client: uses (evidence: `src/app/settings/member-actions.ts`)
- Local trip board → Family member: organises demo ideas
- Family workspace shell → Server Supabase client: loads household data (evidence: `src/components/family-shell.tsx`)
- Server Supabase client → Supabase: accesses (evidence: `src/lib/supabase/server.ts`)
- Browser Supabase client → Supabase: accesses (evidence: `src/lib/supabase/client.ts`)
