# saadferozee/nooks architecture

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

- Interactive diagram: https://gitdiagram.com/saadferozee/nooks
- Repository: https://github.com/saadferozee/nooks

## Overview

Nooks is a Next.js messaging app backed by Supabase. The user journey spans authentication and username onboarding, finding someone, starting or opening a conversation, and chatting; the root layout also mounts auth and presence tracking. The README documents group chat, typing, read receipts, and media, but the sampled source does not establish their implementation details, so those capabilities are represented as documented features with uncertain wiring omitted. Arrows reflect sampled calls and explicit README architecture; unsampled routes and feature internals are not inferred.

Main entry points: [`components/chat/UserSearch.tsx`](https://github.com/saadferozee/nooks/blob/main/components/chat/UserSearch.tsx) (User search), [`app/auth/callback/route.ts`](https://github.com/saadferozee/nooks/blob/main/app/auth/callback/route.ts) (Auth callback), [`components/auth/AuthListener.tsx`](https://github.com/saadferozee/nooks/blob/main/components/auth/AuthListener.tsx) (Auth listener), [`libraries/hooks/useUserSearch.ts`](https://github.com/saadferozee/nooks/blob/main/libraries/hooks/useUserSearch.ts) (Search hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_root["Root layout<br/>[layout.tsx]"]
  node_main["Main layout<br/>[layout.tsx]"]
  node_chatroute["Conversation route<br/>[page.tsx]"]
end

subgraph group_identity["Identity"]
  node_login["Login page<br/>[page.tsx]"]
  node_signup["Signup page<br/>[page.tsx]"]
  node_callback["Auth callback<br/>[route.ts]"]
  node_onboarding["Username onboarding<br/>[page.tsx]"]
  node_authui["Auth forms"]
  node_authlistener["Auth listener<br/>[AuthListener.tsx]"]
  node_authstore["Auth state<br/>[AuthStore.ts]"]
end

subgraph group_messaging["Messaging"]
  node_conversations["Conversation list"]
  node_search["User search<br/>[UserSearch.tsx]"]
  node_searchhook["Search hook<br/>[useUserSearch.ts]"]
  node_start["Start conversation"]
  node_thread["Chat thread<br/>[ChatThread.tsx]"]
  node_presence["Presence tracker"]
  node_realtime["Realtime features"]
  node_media["Media sharing"]
end

subgraph group_backend["Supabase access"]
  node_client["Browser client<br/>[client.ts]"]
  node_serverclient["Server client<br/>[server.ts]"]
  node_supabase[("Supabase services")]
end

node_user(("User"))

node_user -->|"signs in"| node_login
node_user -->|"registers"| node_signup
node_login -->|"renders"| node_authui
node_signup -->|"renders"| node_authui
node_root -->|"mounts"| node_authlistener
node_root -->|"mounts"| node_presence
node_authlistener -->|"creates client"| node_client
node_authlistener -->|"updates state"| node_authstore
node_callback -->|"exchanges code"| node_supabase
node_callback -->|"reads profile"| node_supabase
node_callback -->|"redirects"| node_onboarding
node_main -->|"renders"| node_conversations
node_main -->|"hosts"| node_chatroute
node_conversations -->|"provides search"| node_search
node_search -->|"searches users"| node_searchhook
node_search -->|"starts conversation"| node_start
node_search -->|"reads user"| node_authstore
node_searchhook -->|"creates client"| node_client
node_searchhook -->|"queries profiles"| node_supabase
node_start -->|"creates client"| node_client
node_start -->|"reads and writes"| node_supabase
node_chatroute -->|"renders"| node_thread
node_presence -.->|"tracks presence"| node_supabase
node_user -->|"finds people"| node_search
node_user -->|"sends messages"| node_thread

click node_root "https://github.com/saadferozee/nooks/blob/main/app/layout.tsx"
click node_main "https://github.com/saadferozee/nooks/blob/main/app/(main)/layout.tsx"
click node_login "https://github.com/saadferozee/nooks/blob/main/app/(auth)/login/page.tsx"
click node_signup "https://github.com/saadferozee/nooks/blob/main/app/(auth)/signup/page.tsx"
click node_callback "https://github.com/saadferozee/nooks/blob/main/app/auth/callback/route.ts"
click node_onboarding "https://github.com/saadferozee/nooks/blob/main/app/onboarding/username/page.tsx"
click node_authui "https://github.com/saadferozee/nooks/tree/main/components/auth"
click node_authlistener "https://github.com/saadferozee/nooks/blob/main/components/auth/AuthListener.tsx"
click node_authstore "https://github.com/saadferozee/nooks/blob/main/libraries/stores/AuthStore.ts"
click node_conversations "https://github.com/saadferozee/nooks/blob/main/components/chat/ConversationList.tsx"
click node_search "https://github.com/saadferozee/nooks/blob/main/components/chat/UserSearch.tsx"
click node_searchhook "https://github.com/saadferozee/nooks/blob/main/libraries/hooks/useUserSearch.ts"
click node_start "https://github.com/saadferozee/nooks/blob/main/libraries/hooks/useStartConversation.ts"
click node_thread "https://github.com/saadferozee/nooks/blob/main/components/chat/ChatThread.tsx"
click node_chatroute "https://github.com/saadferozee/nooks/blob/main/app/(main)/chat/%5BconversationId%5D/page.tsx"
click node_presence "https://github.com/saadferozee/nooks/blob/main/components/chat/PresenceTracker.tsx"
click node_client "https://github.com/saadferozee/nooks/blob/main/libraries/supabase/client.ts"
click node_serverclient "https://github.com/saadferozee/nooks/blob/main/libraries/supabase/server.ts"
click node_realtime "https://github.com/saadferozee/nooks/tree/main/components/chat"
click node_media "https://github.com/saadferozee/nooks/tree/main/components/chat"

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_root,node_main,node_chatroute,node_user toneBlue
class node_login,node_signup,node_callback,node_onboarding,node_authui,node_authlistener,node_authstore toneAmber
class node_conversations,node_search,node_searchhook,node_start,node_thread,node_presence,node_realtime,node_media toneMint
class node_client,node_serverclient,node_supabase toneRose
```

## Components

### App entry

- [Root layout](https://github.com/saadferozee/nooks/blob/main/app/layout.tsx): `app/layout.tsx`
- [Main layout](https://github.com/saadferozee/nooks/blob/main/app/(main)/layout.tsx): `app/(main)/layout.tsx`
- [Conversation route](https://github.com/saadferozee/nooks/blob/main/app/(main)/chat/%5BconversationId%5D/page.tsx): `app/(main)/chat/[conversationId]/page.tsx`

### Identity

- [Login page](https://github.com/saadferozee/nooks/blob/main/app/(auth)/login/page.tsx): `app/(auth)/login/page.tsx`
- [Signup page](https://github.com/saadferozee/nooks/blob/main/app/(auth)/signup/page.tsx): `app/(auth)/signup/page.tsx`
- [Auth callback](https://github.com/saadferozee/nooks/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Username onboarding](https://github.com/saadferozee/nooks/blob/main/app/onboarding/username/page.tsx): `app/onboarding/username/page.tsx`
- [Auth forms](https://github.com/saadferozee/nooks/tree/main/components/auth): `components/auth`
- [Auth listener](https://github.com/saadferozee/nooks/blob/main/components/auth/AuthListener.tsx): `components/auth/AuthListener.tsx`
- [Auth state](https://github.com/saadferozee/nooks/blob/main/libraries/stores/AuthStore.ts): `libraries/stores/AuthStore.ts`

### Messaging

- [Conversation list](https://github.com/saadferozee/nooks/blob/main/components/chat/ConversationList.tsx): `components/chat/ConversationList.tsx`
- [User search](https://github.com/saadferozee/nooks/blob/main/components/chat/UserSearch.tsx): `components/chat/UserSearch.tsx`
- [Search hook](https://github.com/saadferozee/nooks/blob/main/libraries/hooks/useUserSearch.ts): `libraries/hooks/useUserSearch.ts`
- [Start conversation](https://github.com/saadferozee/nooks/blob/main/libraries/hooks/useStartConversation.ts): `libraries/hooks/useStartConversation.ts`
- [Chat thread](https://github.com/saadferozee/nooks/blob/main/components/chat/ChatThread.tsx): `components/chat/ChatThread.tsx`
- [Presence tracker](https://github.com/saadferozee/nooks/blob/main/components/chat/PresenceTracker.tsx): `components/chat/PresenceTracker.tsx`
- [Realtime features](https://github.com/saadferozee/nooks/tree/main/components/chat): `components/chat`
- [Media sharing](https://github.com/saadferozee/nooks/tree/main/components/chat): `components/chat`

### Supabase access

- [Browser client](https://github.com/saadferozee/nooks/blob/main/libraries/supabase/client.ts): `libraries/supabase/client.ts`
- [Server client](https://github.com/saadferozee/nooks/blob/main/libraries/supabase/server.ts): `libraries/supabase/server.ts`
- **Supabase services**

### Other components

- **User**

## Connections

- User → Login page: signs in
- User → Signup page: registers
- Login page → Auth forms: renders
- Signup page → Auth forms: renders
- Root layout → Auth listener: mounts
- Root layout → Presence tracker: mounts
- Auth listener → Browser client: creates client
- Auth listener → Auth state: updates state
- Auth callback → Supabase services: exchanges code
- Auth callback → Supabase services: reads profile
- Auth callback → Username onboarding: redirects
- Main layout → Conversation list: renders
- Main layout → Conversation route: hosts
- Conversation list → User search: provides search
- User search → Search hook: searches users
- User search → Start conversation: starts conversation
- User search → Auth state: reads user
- Search hook → Browser client: creates client
- Search hook → Supabase services: queries profiles
- Start conversation → Browser client: creates client
- Start conversation → Supabase services: reads and writes
- Conversation route → Chat thread: renders
- Presence tracker → Supabase services: tracks presence
- User → User search: finds people
- User → Chat thread: sends messages