# baibhavbaidya/unspoken architecture

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

- Interactive diagram: https://gitdiagram.com/baibhavbaidya/unspoken
- Repository: https://github.com/baibhavbaidya/unspoken

## Overview

##### Project type & purpose (from file tree + README)
This is a **full-stack Next.js (App Router) application**. Even though the README is the default template, the file tree shows it’s not “just frontend”:
- **UI + routing:** `app/**` pages and layouts (App Router)
- **Backend endpoints:** `app/api/**/route.ts` (Next.js Route Handlers = server-side API)
- **Authentication:** `app/auth/*` pages, `components/auth/ProtectedRoute.tsx`, `lib/auth-context.tsx`, `lib/firebase.ts`
- **LLM integration:** `lib/groq.ts`, `lib/prompts.ts`, plus API routes like `app/api/generate/route.ts` and `app/api/conversation/route.ts`
- **Domain concept:** “bottles” and a multi-step “create” flow (`app/bottles/**`, `app/create/**`)

- client-rendered UI (React components)
- server-rendered routes
- serverless API endpoints
- external services (Firebase + Groq)

##### Reusable UI + client logic
- UI components: `components/ui/*` (navbar, hero, flowing-waves)
- Auth gating: `components/auth/ProtectedRoute.tsx`
- Hooks: `hooks/use-mobile.tsx`, `hooks/use-toast.ts`
- Types: `types/index.ts`

##### Server-side API surface (Backend inside Next.js)
- `app/api/generate/route.ts`
- `app/api/conversation/route.ts`

##### Shared “services” / integration layer (`lib/*`)
- `lib/firebase.ts` (Firebase client/admin initialization and config)
- `lib/auth-context.tsx` (auth state + context provider)
- `lib/groq.ts` (Groq API client / wrapper)
- `lib/prompts.ts` (prompt templates / prompt assembly)
- `lib/utils.ts` (shared utilities)

##### External dependencies / infrastructure
- **Firebase** (definitely Auth; possibly Firestore/Storage—confirm by checking `lib/firebase.ts` usage)
- **Groq API** (LLM generation / conversation)

##### Firebase Auth ↔ Browser/Next.js client (token-based session)

- Browser UI → Firebase Auth
- Browser UI → Next.js pages/components (obvious)
- ProtectedRoute/AuthContext → Firebase Auth SDK

##### Server calls Groq API
5. Response returns to UI to render results in `/create/generate` and subsequent steps (`edit`, `deliver`)

- Browser → Next.js API route (`/api/generate`, `/api/conversation`)
- API route → Groq API
- API route → prompt templates (internal dependency)
- API route → (optional) Firebase/DB if outputs are persisted (likely given “bottles”)

##### Bottles CRUD (domain data)
Pages suggest:
- `/bottles`
- detail: `/bottles/[bottleId]`
- create: `/bottles/create`

- Browser/pages → Firebase DB (or Next.js server → Firebase DB) depending on whether reads/writes happen client-side or via server routes.

- “End User (Browser)”
- “Next.js App (this repo)”
- “Firebase (Auth + DB)”
- “Groq API”

- User ↔ Next.js App
- Next.js App ↔ Firebase
- Next.js App ↔ Groq

Split “Next.js App” into:
- **Web UI (App Router pages + components)**
- **API Routes (Route Handlers)**: `/api/generate`, `/api/conversation`
- **Shared Libraries**: `lib/firebase`, `lib/groq`, `lib/prompts`, `lib/auth-context`

External containers:
- Firebase Auth
- Firebase DB/Storage (if used)
- Groq API

- `POST /api/generate` → uses `lib/prompts` → uses `lib/groq` → calls Groq
- `POST /api/conversation` → conversation state handling (if any) → uses `lib/groq`

Shared helpers from `lib/utils.ts` and shared `types/`.

- Next.js **App Router** (`app/`)
- **Route Handlers** (`app/api/*/route.ts`)
- **Firebase** (Auth; DB if present)
- **Groq** (LLM inference)
- Styling/UI: **Tailwind CSS** (`tailwind.config.ts`, `postcss.config.mjs`, `app/globals.css`)
- Typescript everywhere (`tsconfig.json`, `*.ts/tsx`)

“Deployment” annotation:
- “Vercel Serverless Functions” (or “Node server runtime”) for API routes

Include:
- **Clear labels**: use route names and folder names (e.g., “/api/generate”, “Create flow pages: /create/interview|generate|edit|deliver”)
- Blue rectangles: Frontend UI (pages/components)
- Orange rectangles: Backend API routes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (L1)
    %% =========================
    U["End User (Browser)"]:::external

    subgraph "Next.js Full-Stack App (Single Deployable)"
        NX["Next.js App (App Router + Route Handlers)"]:::platform
    end

    FB["Firebase (Auth + DB/Storage)"]:::external
    GROQ["Groq API (LLM Inference)"]:::external

    U -->|"navigates|SSR/CSR"| NX
    NX -->|"authSDK/dbSDK"| FB
    NX -->|"httpsAPI"| GROQ

    %% =========================
    %% Container Diagram (L2)
    %% =========================
    subgraph "Next.js App Containers (Vercel/Node Runtime)"
        direction TB

        subgraph "Presentation (Web UI: app/** pages + components)"
            direction TB
            UI_Shell["App Router Shell (layout/home/globals)"]:::frontend
            UI_AuthPages["Auth Pages (/auth/login, /auth/signup)"]:::frontend
            UI_Dashboard["Dashboard Page (/dashboard)"]:::frontend
            UI_Bottles["Bottles Pages (/bottles, /bottles/[id], /bottles/create)"]:::frontend
            UI_CreateFlow["Create Flow Pages (/create/*)"]:::frontend

            UI_Components["Reusable UI Components (Navbar/Hero/Visuals)"]:::frontend
            UI_Protected["ProtectedRoute (Auth Gating)"]:::frontend
            UI_Hooks["Client Hooks (use-mobile/use-toast)"]:::frontend
        end

        subgraph "Backend (Route Handlers: app/api/**)"
            direction TB
            API_Generate["POST /api/generate (Serverless Function)"]:::backend
            API_Conversation["POST /api/conversation (Serverless Function)"]:::backend
        end

        subgraph "Shared Libraries (lib/** + types/**)"
            direction TB
            LIB_AuthCtx["Auth Context Provider"]:::shared
            LIB_Firebase["Firebase SDK Init/Config"]:::shared
            LIB_Groq["Groq Client/Wrapper"]:::shared
            LIB_Prompts["Prompt Templates/Assembly"]:::shared
            LIB_Utils["Shared Utils"]:::shared
            TYPES["Shared Types"]:::shared
        end

        subgraph "Styling Tooling"
            direction TB
            STYLE["Tailwind CSS + PostCSS"]:::tooling
        end
    end

    %% UI navigation + composition
    U -->|"renders"| UI_Shell
    UI_Shell -->|"routesTo"| UI_AuthPages
    UI_Shell -->|"routesTo"| UI_Dashboard
    UI_Shell -->|"routesTo"| UI_Bottles
    UI_Shell -->|"routesTo"| UI_CreateFlow

    UI_Shell -->|"uses"| UI_Components
    UI_Dashboard -->|"uses"| UI_Protected
    UI_Bottles -->|"uses"| UI_Protected
    UI_CreateFlow -->|"uses"| UI_Protected
    UI_AuthPages -->|"uses"| UI_Components
    UI_CreateFlow -->|"uses"| UI_Hooks

    %% Auth wiring
    UI_Protected -->|"readsAuthState"| LIB_AuthCtx
    UI_AuthPages -->|"updatesAuthState"| LIB_AuthCtx
    LIB_AuthCtx -->|"uses"| LIB_Firebase
    LIB_Firebase -->|"Auth|DB|Storage"| FB

    %% LLM flows
    UI_CreateFlow -->|"fetch('/api/generate')"| API_Generate
    UI_CreateFlow -->|"fetch('/api/conversation')"| API_Conversation

    API_Generate -->|"uses"| LIB_Prompts
    API_Generate -->|"uses"| LIB_Groq
    API_Generate -->|"uses"| LIB_Utils
    API_Generate -->|"uses"| TYPES

    API_Conversation -->|"uses"| LIB_Groq
    API_Conversation -->|"uses"| LIB_Utils
    API_Conversation -->|"uses"| TYPES

    LIB_Groq -->|"callsLLM"| GROQ

    %% Bottles data (client-side or server-side via Firebase SDK)
    UI_Bottles -->|"read/writeDomainData"| LIB_Firebase
    UI_CreateFlow -->|"optionalPersistOutputs"| LIB_Firebase

    %% Styling
    UI_Shell -->|"styles"| STYLE
    UI_Components -->|"styles"| STYLE

    %% =========================
    %% Backend Component Focus (L3-ish)
    %% =========================
    subgraph "API Endpoint Internals (Component View)"
        direction TB

        subgraph "POST /api/generate"
            direction TB
            GEN_In["Request (Interview Inputs)"]:::backendLight
            GEN_Prompt["Prompt Assembly"]:::sharedLight
            GEN_LLM["Groq Inference Call"]:::externalLight
            GEN_Out["Response (Generated Draft/Steps)"]:::backendLight

            GEN_In -->|"buildPrompt"| GEN_Prompt
            GEN_Prompt -->|"invoke"| GEN_LLM
            GEN_LLM -->|"result"| GEN_Out
        end

        subgraph "POST /api/conversation"
            direction TB
            CONV_In["Request (Messages/Context)"]:::backendLight
            CONV_LLM["Groq Chat Call"]:::externalLight
            CONV_Out["Response (Assistant Reply)"]:::backendLight

            CONV_In -->|"invoke"| CONV_LLM
            CONV_LLM -->|"result"| CONV_Out
        end
    end

    API_Generate -->|"handles"| GEN_In
    GEN_LLM -->|"httpsAPI"| GROQ
    API_Conversation -->|"handles"| CONV_In
    CONV_LLM -->|"httpsAPI"| GROQ

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click UI_Shell "https://github.com/baibhavbaidya/unspoken/blob/main/app/layout.tsx"
    click UI_Shell "https://github.com/baibhavbaidya/unspoken/blob/main/app/page.tsx"
    click UI_Shell "https://github.com/baibhavbaidya/unspoken/blob/main/app/globals.css"

    click UI_AuthPages "https://github.com/baibhavbaidya/unspoken/blob/main/app/auth/login/page.tsx"
    click UI_AuthPages "https://github.com/baibhavbaidya/unspoken/blob/main/app/auth/signup/page.tsx"

    click UI_Dashboard "https://github.com/baibhavbaidya/unspoken/blob/main/app/dashboard/page.tsx"

    click UI_Bottles "https://github.com/baibhavbaidya/unspoken/blob/main/app/bottles/page.tsx"
    click UI_Bottles "https://github.com/baibhavbaidya/unspoken/blob/main/app/bottles/[bottleId]/page.tsx"
    click UI_Bottles "https://github.com/baibhavbaidya/unspoken/blob/main/app/bottles/create/page.tsx"

    click UI_CreateFlow "https://github.com/baibhavbaidya/unspoken/blob/main/app/create/page.tsx"
    click UI_CreateFlow "https://github.com/baibhavbaidya/unspoken/blob/main/app/create/interview/page.tsx"
    click UI_CreateFlow "https://github.com/baibhavbaidya/unspoken/blob/main/app/create/generate/page.tsx"
    click UI_CreateFlow "https://github.com/baibhavbaidya/unspoken/blob/main/app/create/edit/page.tsx"
    click UI_CreateFlow "https://github.com/baibhavbaidya/unspoken/blob/main/app/create/deliver/page.tsx"

    click API_Conversation "https://github.com/baibhavbaidya/unspoken/blob/main/app/api/conversation/route.ts"
    click API_Generate "https://github.com/baibhavbaidya/unspoken/blob/main/app/api/generate/route.ts"

    click UI_Protected "https://github.com/baibhavbaidya/unspoken/blob/main/components/auth/ProtectedRoute.tsx"

    click UI_Components "https://github.com/baibhavbaidya/unspoken/blob/main/components/ui/navbar.tsx"
    click UI_Components "https://github.com/baibhavbaidya/unspoken/blob/main/components/ui/hero-section.tsx"
    click UI_Components "https://github.com/baibhavbaidya/unspoken/blob/main/components/ui/flowing-waves.tsx"

    click UI_Hooks "https://github.com/baibhavbaidya/unspoken/blob/main/hooks/use-mobile.tsx"
    click UI_Hooks "https://github.com/baibhavbaidya/unspoken/blob/main/hooks/use-toast.ts"

    click TYPES "https://github.com/baibhavbaidya/unspoken/blob/main/types/index.ts"

    click LIB_AuthCtx "https://github.com/baibhavbaidya/unspoken/blob/main/lib/auth-context.tsx"
    click LIB_Firebase "https://github.com/baibhavbaidya/unspoken/blob/main/lib/firebase.ts"
    click LIB_Groq "https://github.com/baibhavbaidya/unspoken/blob/main/lib/groq.ts"
    click LIB_Prompts "https://github.com/baibhavbaidya/unspoken/blob/main/lib/prompts.ts"
    click LIB_Utils "https://github.com/baibhavbaidya/unspoken/blob/main/lib/utils.ts"

    click STYLE "https://github.com/baibhavbaidya/unspoken/blob/main/tailwind.config.ts"
    click STYLE "https://github.com/baibhavbaidya/unspoken/blob/main/postcss.config.mjs"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#6D28D9,stroke:#2E1065,color:#FFFFFF,stroke-width:1.5px
    classDef platform fill:#0F172A,stroke:#1E293B,color:#FFFFFF,stroke-width:1.5px

    classDef frontend fill:#1D4ED8,stroke:#1E3A8A,color:#FFFFFF,stroke-width:1.5px
    classDef backend fill:#F97316,stroke:#9A3412,color:#111827,stroke-width:1.5px
    classDef shared fill:#14B8A6,stroke:#0F766E,color:#062A2A,stroke-width:1.5px
    classDef tooling fill:#64748B,stroke:#334155,color:#FFFFFF,stroke-width:1.5px

    classDef backendLight fill:#FDBA74,stroke:#C2410C,color:#111827,stroke-width:1.2px
    classDef sharedLight fill:#5EEAD4,stroke:#0F766E,color:#062A2A,stroke-width:1.2px
    classDef externalLight fill:#C4B5FD,stroke:#4C1D95,color:#111827,stroke-width:1.2px
```
