# amin-nepali/omnimail-central architecture

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

- Interactive diagram: https://gitdiagram.com/amin-nepali/omnimail-central
- Repository: https://github.com/amin-nepali/omnimail-central

## Overview

OmniMail Central is a local-first dashboard for combining read-only Gmail from multiple Google accounts. The main workflow links accounts through Google OAuth, stores account credentials in Firestore, then syncs recent Inbox, Spam, and Trash messages from Gmail for display, search, filtering, and detail viewing. The sampled server owns the API operations and transforms Gmail payloads through the message extractor; the browser calls those endpoints. The Vercel adapter delegates requests to the same server. Some planned capabilities are documented but their implementation was not sampled.

Main entry points: [`public/app.js`](https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js) (Inbox dashboard), [`server.js`](https://github.com/amin-nepali/omnimail-central/blob/main/server.js) (API server), [`lib/messages.js`](https://github.com/amin-nepali/omnimail-central/blob/main/lib/messages.js) (Message extraction), [`api/[...route].js`](https://github.com/amin-nepali/omnimail-central/blob/main/api/%5B...route%5D.js) (Vercel API adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Inbox dashboard<br/>[app.js]"]
  node_message_views["Search and views<br/>[app.js]"]
  node_message_detail["Message details<br/>[app.js]"]
  node_workspace_access["Workspace sign-in<br/>[app.js]"]
end

subgraph group_api["API and access"]
  node_api_adapter["Vercel API adapter<br/>[&#91;...route&#93;.js]"]
  node_server["API server<br/>[server.js]"]
end

subgraph group_mail["Mail workflow"]
  node_oauth_flow["Google account linking<br/>[server.js]"]
  node_account_management["Connected accounts<br/>[server.js]"]
  node_mail_sync["Category sync<br/>[server.js]"]
  node_message_extract["Message extraction<br/>[messages.js]"]
end

subgraph group_integrations["External services"]
  node_gmail["Gmail API"]
  node_google_oauth["Google OAuth"]
  node_firestore[("Firestore accounts")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"signs in"| node_workspace_access
node_dashboard_ui -->|"requests"| node_server
node_dashboard_ui -->|"renders"| node_message_views
node_message_views -->|"opens"| node_message_detail
node_dashboard_ui -->|"starts linking"| node_oauth_flow
node_dashboard_ui -->|"requests sync"| node_mail_sync
node_api_adapter -->|"delegates to"| node_server
node_server -->|"routes OAuth"| node_oauth_flow
node_oauth_flow -->|"exchanges code"| node_google_oauth
node_oauth_flow -->|"stores credentials"| node_firestore
node_server -->|"serves account requests"| node_account_management
node_account_management -->|"reads and deletes"| node_firestore
node_server -->|"handles sync"| node_mail_sync
node_mail_sync -->|"reads accounts"| node_firestore
node_mail_sync -->|"lists and fetches"| node_gmail
node_mail_sync -->|"normalizes messages"| node_message_extract
node_message_extract -->|"returns message data"| node_dashboard_ui
node_server -->|"checks sessions"| node_workspace_access

click node_dashboard_ui "https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js"
click node_message_views "https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js"
click node_message_detail "https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js"
click node_workspace_access "https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js"
click node_api_adapter "https://github.com/amin-nepali/omnimail-central/blob/main/api/%5B...route%5D.js"
click node_server "https://github.com/amin-nepali/omnimail-central/blob/main/server.js"
click node_oauth_flow "https://github.com/amin-nepali/omnimail-central/blob/main/server.js"
click node_account_management "https://github.com/amin-nepali/omnimail-central/blob/main/server.js"
click node_mail_sync "https://github.com/amin-nepali/omnimail-central/blob/main/server.js"
click node_message_extract "https://github.com/amin-nepali/omnimail-central/blob/main/lib/messages.js"

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_dashboard_ui,node_message_views,node_message_detail,node_workspace_access toneBlue
class node_api_adapter,node_server toneAmber
class node_oauth_flow,node_account_management,node_mail_sync,node_message_extract toneMint
class node_gmail,node_google_oauth,node_firestore toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [Inbox dashboard](https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js): `public/app.js`
- [Search and views](https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js): `public/app.js`
- [Message details](https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js): `public/app.js`
- [Workspace sign-in](https://github.com/amin-nepali/omnimail-central/blob/main/public/app.js): `public/app.js`

### API and access

- [Vercel API adapter](https://github.com/amin-nepali/omnimail-central/blob/main/api/%5B...route%5D.js): `api/[...route].js`
- [API server](https://github.com/amin-nepali/omnimail-central/blob/main/server.js): `server.js`

### Mail workflow

- [Google account linking](https://github.com/amin-nepali/omnimail-central/blob/main/server.js): `server.js`
- [Connected accounts](https://github.com/amin-nepali/omnimail-central/blob/main/server.js): `server.js`
- [Category sync](https://github.com/amin-nepali/omnimail-central/blob/main/server.js): `server.js`
- [Message extraction](https://github.com/amin-nepali/omnimail-central/blob/main/lib/messages.js): `lib/messages.js`

### External services

- **Gmail API**
- **Google OAuth**
- **Firestore accounts**

### Other components

- **Operator**

## Connections

- Operator → Inbox dashboard: uses (evidence: `README.md`)
- Inbox dashboard → Workspace sign-in: signs in (evidence: `public/app.js`)
- Inbox dashboard → API server: requests (evidence: `public/app.js`)
- Inbox dashboard → Search and views: renders (evidence: `public/app.js`)
- Search and views → Message details: opens (evidence: `public/app.js`)
- Inbox dashboard → Google account linking: starts linking (evidence: `public/app.js`)
- Inbox dashboard → Category sync: requests sync (evidence: `public/app.js`)
- Vercel API adapter → API server: delegates to (evidence: `api/[...route].js`)
- API server → Google account linking: routes OAuth (evidence: `server.js`)
- Google account linking → Google OAuth: exchanges code (evidence: `README.md`)
- Google account linking → Firestore accounts: stores credentials (evidence: `server.js`)
- API server → Connected accounts: serves account requests (evidence: `server.js`)
- Connected accounts → Firestore accounts: reads and deletes (evidence: `server.js`)
- API server → Category sync: handles sync (evidence: `server.js`)
- Category sync → Firestore accounts: reads accounts (evidence: `server.js`)
- Category sync → Gmail API: lists and fetches (evidence: `server.js`)
- Category sync → Message extraction: normalizes messages (evidence: `server.js`)
- Message extraction → Inbox dashboard: returns message data (evidence: `README.md`)
- API server → Workspace sign-in: checks sessions (evidence: `server.js`)