How puneet2404/nebulamail works
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