# martingaolianzhan/mindmail architecture

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

- Interactive diagram: https://gitdiagram.com/martingaolianzhan/mindmail
- Repository: https://github.com/martingaolianzhan/mindmail

## Overview

Mind Mail is a web email client centered on connecting an email account, synchronizing messages, and managing them in the mail interface. The documented feature set also includes message composition, AI assistance, and search. Sampled code confirms the Aurinko callback and initial-sync path, database-backed search, and the client’s search request; other UI and router internals are represented at the enclosing paths shown in the tree, so their specific wiring is not assumed.

Main entry points: [`src/server/db.ts`](https://github.com/martingaolianzhan/mindmail/blob/main/src/server/db.ts) (Application database), [`src/app/api/aurinko/callback/route.ts`](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/aurinko/callback/route.ts) (Account callback), [`src/app/api/initial-sync/route.ts`](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/initial-sync/route.ts) (Initial sync), [`src/app/mail/mail.tsx`](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/mail.tsx) (Mail workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mail["Mail experience"]
  node_mail_page["Mail page<br/>[page.tsx]"]
  node_mail_shell["Mail workspace<br/>[mail.tsx]"]
  node_thread_list["Thread list<br/>[thread-list.tsx]"]
  node_thread_display["Thread view<br/>[thread-display.tsx]"]
  node_email_display["Email view<br/>[email-display.tsx]"]
  node_composer["Compose and reply<br/>[compose-button.tsx]"]
  node_editor["Email editor<br/>[email-editor.tsx]"]
  node_ai_compose["AI assistant<br/>[ai-actions.ts]"]
  node_search_ui["Email search<br/>[search-display.tsx]"]
  node_search_bar["Search input<br/>[search-bar.tsx]"]
  node_account_ui["Account controls"]
end

subgraph group_account["Accounts and sync"]
  node_connect["Account callback<br/>[route.ts]"]
  node_aurinko_lib["Aurinko client<br/>[aurinko.ts]"]
  node_initial_sync["Initial sync<br/>[route.ts]"]
  node_account_lib["Account sync<br/>[account.ts]"]
  node_sync_store["Email persistence<br/>[sync-to-db.ts]"]
  node_clerk_webhook["User webhook<br/>[route.ts]"]
end

subgraph group_backend["API and data"]
  node_trpc_http["tRPC endpoint<br/>[route.ts]"]
  node_app_router["API router<br/>[root.ts]"]
  node_account_router["Account API<br/>[account.ts]"]
  node_search_lib["Search service<br/>[search.ts]"]
  node_database[("Application database<br/>[db.ts]")]
end

subgraph group_integrations["External services"]
  node_aurinko{{"Aurinko"}}
  node_clerk{{"Clerk"}}
  node_gemini{{"Google Gemini"}}
  node_neon[("Neon PostgreSQL")]
end

node_user(("User"))

node_user -->|"opens"| node_mail_page
node_mail_page -->|"renders"| node_mail_shell
node_mail_shell -->|"shows threads"| node_thread_list
node_mail_shell -->|"shows thread"| node_thread_display
node_thread_display -->|"renders messages"| node_email_display
node_user -->|"composes"| node_composer
node_composer -->|"opens editor"| node_editor
node_editor -.->|"requests assistance"| node_ai_compose
node_ai_compose -.->|"generates text"| node_gemini
node_user -->|"enters query"| node_search_bar
node_search_bar -->|"updates query"| node_search_ui
node_search_ui -->|"calls mutation"| node_account_router
node_account_router -->|"searches emails"| node_search_lib
node_search_lib -->|"reads emails"| node_database
node_user -->|"manages account"| node_account_ui
node_account_ui -->|"connects account"| node_connect
node_aurinko -->|"returns authorization"| node_connect
node_connect -->|"exchanges token"| node_aurinko_lib
node_connect -->|"upserts account"| node_database
node_connect -->|"triggers sync"| node_initial_sync
node_initial_sync -->|"loads account"| node_database
node_initial_sync -->|"fetches messages"| node_account_lib
node_account_lib -->|"syncs messages"| node_aurinko
node_initial_sync -->|"persists messages"| node_sync_store
node_sync_store -->|"upserts emails"| node_database
node_clerk -->|"sends user event"| node_clerk_webhook
node_clerk_webhook -->|"upserts user"| node_database
node_user -->|"requests API"| node_trpc_http
node_trpc_http -->|"dispatches"| node_app_router
node_database -->|"stores data"| node_neon

click node_mail_page "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/page.tsx"
click node_mail_shell "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/mail.tsx"
click node_thread_list "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/thread-list.tsx"
click node_thread_display "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/thread-display.tsx"
click node_email_display "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-display.tsx"
click node_composer "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/compose-button.tsx"
click node_editor "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-editor/email-editor.tsx"
click node_ai_compose "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/ai-compose/ai-actions.ts"
click node_search_ui "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-search/search-display.tsx"
click node_search_bar "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-search/search-bar.tsx"
click node_account_ui "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/account-switcher.tsx"
click node_connect "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/aurinko/callback/route.ts"
click node_aurinko_lib "https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/aurinko.ts"
click node_initial_sync "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/initial-sync/route.ts"
click node_account_lib "https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/account.ts"
click node_sync_store "https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/sync-to-db.ts"
click node_clerk_webhook "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/clerk/webhook/route.ts"
click node_trpc_http "https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/trpc/%5Btrpc%5D/route.ts"
click node_app_router "https://github.com/martingaolianzhan/mindmail/blob/main/src/server/api/root.ts"
click node_account_router "https://github.com/martingaolianzhan/mindmail/blob/main/src/server/api/routers/account.ts"
click node_search_lib "https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/search.ts"
click node_database "https://github.com/martingaolianzhan/mindmail/blob/main/src/server/db.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_mail_page,node_mail_shell,node_thread_list,node_thread_display,node_email_display,node_composer,node_editor,node_ai_compose,node_search_ui,node_search_bar,node_account_ui,node_user toneBlue
class node_connect,node_aurinko_lib,node_initial_sync,node_account_lib,node_sync_store,node_clerk_webhook toneAmber
class node_trpc_http,node_app_router,node_account_router,node_search_lib,node_database toneMint
class node_aurinko,node_clerk,node_gemini,node_neon toneRose
```

## Components

### Mail experience

- [Mail page](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/page.tsx): `src/app/mail/page.tsx`
- [Mail workspace](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/mail.tsx): `src/app/mail/mail.tsx`
- [Thread list](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/thread-list.tsx): `src/app/mail/components/thread-list.tsx`
- [Thread view](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/thread-display.tsx): `src/app/mail/components/thread-display.tsx`
- [Email view](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-display.tsx): `src/app/mail/components/email-display.tsx`
- [Compose and reply](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/compose-button.tsx): `src/app/mail/components/compose-button.tsx`
- [Email editor](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-editor/email-editor.tsx): `src/app/mail/components/email-editor/email-editor.tsx`
- [AI assistant](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/ai-compose/ai-actions.ts): `src/app/mail/components/ai-compose/ai-actions.ts`
- [Email search](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-search/search-display.tsx): `src/app/mail/components/email-search/search-display.tsx`
- [Search input](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/email-search/search-bar.tsx): `src/app/mail/components/email-search/search-bar.tsx`
- [Account controls](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/mail/components/account-switcher.tsx): `src/app/mail/components/account-switcher.tsx`

### Accounts and sync

- [Account callback](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/aurinko/callback/route.ts): `src/app/api/aurinko/callback/route.ts`
- [Aurinko client](https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/aurinko.ts): `src/lib/aurinko.ts`
- [Initial sync](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/initial-sync/route.ts): `src/app/api/initial-sync/route.ts`
- [Account sync](https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/account.ts): `src/lib/account.ts`
- [Email persistence](https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/sync-to-db.ts): `src/lib/sync-to-db.ts`
- [User webhook](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/clerk/webhook/route.ts): `src/app/api/clerk/webhook/route.ts`

### API and data

- [tRPC endpoint](https://github.com/martingaolianzhan/mindmail/blob/main/src/app/api/trpc/%5Btrpc%5D/route.ts): `src/app/api/trpc/[trpc]/route.ts`
- [API router](https://github.com/martingaolianzhan/mindmail/blob/main/src/server/api/root.ts): `src/server/api/root.ts`
- [Account API](https://github.com/martingaolianzhan/mindmail/blob/main/src/server/api/routers/account.ts): `src/server/api/routers/account.ts`
- [Search service](https://github.com/martingaolianzhan/mindmail/blob/main/src/lib/search.ts): `src/lib/search.ts`
- [Application database](https://github.com/martingaolianzhan/mindmail/blob/main/src/server/db.ts): `src/server/db.ts`

### External services

- **Aurinko**
- **Clerk**
- **Google Gemini**
- **Neon PostgreSQL**

### Other components

- **User**

## Connections

- User → Mail page: opens
- Mail page → Mail workspace: renders
- Mail workspace → Thread list: shows threads
- Mail workspace → Thread view: shows thread
- Thread view → Email view: renders messages
- User → Compose and reply: composes
- Compose and reply → Email editor: opens editor
- Email editor → AI assistant: requests assistance
- AI assistant → Google Gemini: generates text
- User → Search input: enters query
- Search input → Email search: updates query
- Email search → Account API: calls mutation
- Account API → Search service: searches emails
- Search service → Application database: reads emails
- User → Account controls: manages account
- Account controls → Account callback: connects account
- Aurinko → Account callback: returns authorization
- Account callback → Aurinko client: exchanges token
- Account callback → Application database: upserts account
- Account callback → Initial sync: triggers sync
- Initial sync → Application database: loads account
- Initial sync → Account sync: fetches messages
- Account sync → Aurinko: syncs messages
- Initial sync → Email persistence: persists messages
- Email persistence → Application database: upserts emails
- Clerk → User webhook: sends user event
- User webhook → Application database: upserts user
- User → tRPC endpoint: requests API
- tRPC endpoint → API router: dispatches
- Application database → Neon PostgreSQL: stores data