# puneet2404/nebulamail architecture

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

- Interactive diagram: https://gitdiagram.com/puneet2404/nebulamail
- Repository: https://github.com/puneet2404/nebulamail

## Overview

##### Project type and purpose
- This is a full-stack “nebulamail” application combining a Next.js 14 React front-end with an Azure-Functions-based AI-powered backend.
- Purpose: provide an email-style UI with AI-driven features (draft suggestions, classifications, timelines/promises, search, summarizations) backed by Azure OpenAI, Cosmos DB, Azure Cognitive Search, and MSAL SSO.

##### File structure
- Top-level “api” folder: Azure Functions definitions (classify, draftNudge, draftReply, listUnread, mindpalaceSearch, summarisePromises, whyStalled). Contains host.json, local.settings.json, requirements.txt → Python/Azure Functions runtime.
- “__blobstorage__” and AzuriteConfig: local Azure Storage emulator for blob, queue, and table storage.
- “web” folder: Next.js 14 application under “web/app” (app router), “web/components”, “web/hooks”, “web/lib”, “web/providers” (GraphLive orchestrator, LocalMock stub, MailProvider abstraction), “web/public”, configuration (next.config.mjs, tsconfig.json, tailwind.config.cjs).
- Monorepo managed by pnpm (pnpm-workspace.yaml, package.json).

##### Key insights from README
- Front-end: Next.js, React 18, Tailwind CSS, Headless UI, Framer Motion
- Agents & orchestration: Semantic Kernel + Azure AI Agents SDK
- AI services: Azure OpenAI (GPT-4o), AI Search, Content Safety
- Data persistence: Cosmos DB (promises & timelines)
- Auth: MSAL (Microsoft 365 SSO)

##### Main components and interactions
a. Front-end Client (Next.js Web App)
- Components/UI (Inbox, Sidebar, Toasts)
- Hooks & Providers (useAssist, useMailbox; GraphLive orchestrator, MailProvider)
- Auth via MSAL to Azure AD → retrieve tokens
- Calls backend API endpoints (Azure Functions) over HTTPS
b. Backend (Azure Functions)
- Individual serverless functions: classify, draftNudge, draftReply, listUnread, mindpalaceSearch, summarisePromises, whyStalled
- Each function uses Semantic Kernel/Agents SDK to orchestrate calls to OpenAI, Cognitive Search, Content Safety
- Connects to Cosmos DB for reading/writing timelines & promises
- Optionally uses Azure Blob/Queue/Table (Azurite locally)
c. External AI Services
- Azure OpenAI (GPT-4o)
- Azure Cognitive Search for “AI Search”
- Azure Content Safety
d. Data Storage
- Cosmos DB (collections for promises & timelines)
- Azure Storage (blob, queue, table via Azurite for local dev)
e. Authentication
- MSAL / Azure AD for SSO tokens integrated in front-end, validated by backend

##### Architectural patterns and design principles
- Separation of concerns: React UI vs. serverless API layer vs. data & AI services
- Micro-function architecture: small, single-purpose Azure Functions
- Agent orchestration: Semantic Kernel coordinates multi-step AI workflows
- Monorepo with clear folder boundaries for api vs. web
- Local emulation via Azurite for storage services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Front-end Layer
    subgraph "Front-end Client" 
        direction TB
        A1["Next.js App"]:::frontend
        subgraph "App Router (web/app)"
            direction TB
            A2["layout.tsx"]:::frontend
            A3["globals.css"]:::frontend
            A4["inbox/page.tsx"]:::frontend
            A5["marketing/page.tsx"]:::frontend
        end
        subgraph "UI Components (web/components)"
            direction TB
            A6["EmailList.tsx"]:::frontend
            A7["Sidebar.tsx"]:::frontend
            A8["Toast.tsx"]:::frontend
            A9["MailboxBoard.tsx"]:::frontend
            A10["AgentConsole.tsx"]:::frontend
        end
        subgraph "Hooks (web/hooks)"
            direction TB
            A11["useAssist.ts"]:::frontend
            A12["useMailbox.tsx"]:::frontend
        end
        subgraph "Providers (web/providers)"
            direction TB
            A13["GraphLive.ts"]:::frontend
            A14["MailProvider.ts"]:::frontend
            A15["LocalMock.ts"]:::frontend
        end
        A16["Auth Module"]:::auth
    end

    %% Auth Layer
    subgraph "Authentication"
        direction TB
        B1["MSAL SSO"]:::auth
        B2["Azure AD"]:::auth
    end

    %% API Layer
    subgraph "Serverless API (Azure Functions)" 
        direction TB
        C1["classify Function"]:::functions
        C2["draftNudge Function"]:::functions
        C3["draftReply Function"]:::functions
        C4["listUnread Function"]:::functions
        C5["mindpalaceSearch Function"]:::functions
        C6["summarisePromises Function"]:::functions
        C7["whyStalled Function"]:::functions
        C8["host.json / local.settings.json / requirements.txt"]:::functions
    end

    %% Storage Emulator
    subgraph "Local Storage Emulator (Azurite)" 
        direction TB
        D1["__blobstorage__"]:::storage
        D2["AzuriteConfig"]:::storage
    end

    %% AI & Data Services Layer
    subgraph "AI & Data Services"
        direction TB
        E1["Azure OpenAI (GPT-4o)"]:::services
        E2["Azure Cognitive Search"]:::services
        E3["Azure Content Safety"]:::services
        subgraph "Cosmos DB"
            E4["Promises Collection"]:::services
            E5["Timelines Collection"]:::services
        end
        subgraph "Azure Storage (prod)"
            E6["Blob/Queue/Table"]:::services
        end
    end

    %% Relationships
    A1 -->|"calls API over HTTPS"| C1
    A1 -->|"calls API over HTTPS"| C2
    A1 -->|"calls API over HTTPS"| C3
    A1 -->|"calls API over HTTPS"| C4
    A1 -->|"calls API over HTTPS"| C5
    A1 -->|"calls API over HTTPS"| C6
    A1 -->|"calls API over HTTPS"| C7

    A16 -->|"auth request"| B1
    B1 -->|"token"| A1
    B1 -->|"validate"| B2

    C1 -->|"orchestrates via SK"| E1
    C2 -->|"orchestrates via SK"| E1
    C3 -->|"orchestrates via SK"| E1
    C4 -->|"orchestrates via SK"| E2
    C5 -->|"orchestrates via SK"| E2
    C6 -->|"reads/writes"| E4
    C6 -->|"reads/writes"| E5
    C7 -->|"reads"| E5

    C1 -->|"read/write"| E4
    C2 -->|"read/write"| E4
    C3 -->|"read"| E5

    C1 -->|"optional blob"| D1
    C2 -->|"optional blob"| D1

    C8 ---> D2

    subgraph clickHandlers
        click A2 "https://github.com/puneet2404/nebulamail/blob/main/web/app/layout.tsx"
        click A3 "https://github.com/puneet2404/nebulamail/blob/main/web/app/globals.css"
        click A4 "https://github.com/puneet2404/nebulamail/blob/main/web/app/(app)/inbox/page.tsx"
        click A5 "https://github.com/puneet2404/nebulamail/blob/main/web/app/(marketing)/page.tsx"
        click A6 "https://github.com/puneet2404/nebulamail/blob/main/web/components/EmailList.tsx"
        click A7 "https://github.com/puneet2404/nebulamail/blob/main/web/components/Sidebar.tsx"
        click A8 "https://github.com/puneet2404/nebulamail/blob/main/web/components/Toast.tsx"
        click A9 "https://github.com/puneet2404/nebulamail/blob/main/web/components/MailboxBoard.tsx"
        click A10 "https://github.com/puneet2404/nebulamail/blob/main/web/components/AgentConsole.tsx"
        click A11 "https://github.com/puneet2404/nebulamail/blob/main/web/hooks/useAssist.ts"
        click A12 "https://github.com/puneet2404/nebulamail/blob/main/web/hooks/useMailbox.tsx"
        click A13 "https://github.com/puneet2404/nebulamail/blob/main/web/providers/GraphLive.ts"
        click A14 "https://github.com/puneet2404/nebulamail/blob/main/web/providers/MailProvider.ts"
        click A15 "https://github.com/puneet2404/nebulamail/blob/main/web/providers/LocalMock.ts"
        click A16 "https://github.com/puneet2404/nebulamail/blob/main/web/lib/auth.ts"
        click C1 "https://github.com/puneet2404/nebulamail/blob/main/api/classify/__init__.py"
        click C2 "https://github.com/puneet2404/nebulamail/blob/main/api/draftNudge/__init__.py"
        click C3 "https://github.com/puneet2404/nebulamail/blob/main/api/draftReply/__init__.py"
        click C4 "https://github.com/puneet2404/nebulamail/blob/main/api/listUnread/__init__.py"
        click C5 "https://github.com/puneet2404/nebulamail/blob/main/api/mindpalaceSearch/__init__.py"
        click C6 "https://github.com/puneet2404/nebulamail/blob/main/api/summarisePromises/__init__.py"
        click C6 "https://github.com/puneet2404/nebulamail/blob/main/api/summarisePromises/function.json"
        click C7 "https://github.com/puneet2404/nebulamail/blob/main/api/whyStalled/__init__.py"
        click C7 "https://github.com/puneet2404/nebulamail/blob/main/api/whyStalled/function.json"
        click C8 "https://github.com/puneet2404/nebulamail/blob/main/api/host.json"
        click D1 "https://github.com/puneet2404/nebulamail/tree/main/__blobstorage__"
        click D2 "https://github.com/puneet2404/nebulamail/tree/main/api/AzuriteConfig"
    end

    %% Styles
    classDef frontend fill:#D6E8FF,stroke:#0366d6;
    classDef functions fill:#DFF7DF,stroke:#18A349;
    classDef services fill:#FFF4E5,stroke:#E0A800;
    classDef auth fill:#F0E7FF,stroke:#8A05BE;
    classDef storage fill:#F5F5F5,stroke:#666;
```
