# thehalfbldprinc3/smartmirror architecture

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

- Interactive diagram: https://gitdiagram.com/thehalfbldprinc3/smartmirror
- Repository: https://github.com/thehalfbldprinc3/smartmirror

## Overview

##### Project type and purpose
- This is a full-stack, single-page dashboard application (“SmartMirror V2”) built on Next.js (App Router) and TypeScript.
- Purpose: drive a wall-mounted “smart mirror” UI that displays calendar events, weather, news, and hosts an AI-powered voice assistant (Google Gemini + Chrome Web Speech API).

##### File structure
- Top-level “smart-mirror/app” folder holds both UI pages (layout.tsx, page.tsx, sessionWrapper.tsx) and serverless API routes under “app/api”:
- auth/[...nextauth]/route.ts → NextAuth authentication endpoints
- events/route.ts → Google Calendar integration
- weather/route.ts → weather API fetch
- news/route.ts → news API fetch
- gemini/route.ts → proxy to Google Gemini AI
- “smart-mirror/components” contains React widget components (CalendarWidget, WeatherWidget, NewsWidget, ClockWidget, VoiceChatWidget, etc.).
- Configuration files: next.config.ts, tsconfig.json, eslint/postcss configs, package.json.
- No dedicated database folder, implying stateless serverless functions and external-API driven data.

##### README for additional insights
- Confirms tech stack: Next.js, TypeScript, Google Gemini, Chrome Web Speech API, custom React components.
- Features: voice assistant, calendar integration (Google Calendar), weather, news, clock.
- No mention of an internal DB—authentication and state likely managed via NextAuth (JWT or OAuth session).

a. Main components
- Client / Mirror Device (Browser)
- React UI (Widgets + Layout)
- Chrome Web Speech API (voice capture)
- Session wrapper (NextAuth client)
- Next.js Server (hosted on Vercel or similar)
- Frontend SSR/SSG (serves pages)
- Serverless API Routes: Auth, Events, Weather, News, Gemini
- External Services
- Google Gemini API
- Google Calendar API
- Public Weather API (e.g., OpenWeatherMap)
- News API (e.g., NewsAPI.org)
- OAuth Provider (Google) for NextAuth
b. Relationships and interactions
1. User speaks into mic → Web Speech API captures audio → VoiceChatWidget sends transcript to /api/gemini
2. /api/gemini authenticates requests (via NextAuth session), forwards to Google Gemini → receives AI response → returns to client
3. On page load or at intervals, UI calls /api/events, /api/weather, /api/news
4. Each route fetches from its external API, then passes JSON back to React widgets
5. Authentication flows via NextAuth endpoint (/api/auth), interacts with OAuth provider, manages session cookies/JWT
c. Architectural patterns & design principles
- Client-server separation: React client vs. serverless API
- Modular widget-based UI: each piece (news/weather/calendar) is its own component calling its own route
- API façade/gateway: Next.js routes centralize all external API calls and hide keys from the client
- Stateless serverless functions: horizontal scaling, minimal infra
d. Key technologies & frameworks
- Next.js App Router (React + SSR/SSG + API Routes)
- NextAuth for authentication/session management
- TypeScript for type safety
- Chrome Web Speech API (client side)
- Google Gemini API (AI backend)
- Third-party data APIs: Calendar, Weather, News

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client / Mirror Browser"
        CW["CalendarWidget"]:::client
        WW["WeatherWidget"]:::client
        NW["NewsWidget"]:::client
        ClW["ClockWidget"]:::client
        VCW["VoiceChatWidget"]:::client
        HD["Header"]:::client
        SB["signInButtons"]:::client
    end

    %% Server Tier
    subgraph "Next.js Server (Vercel)"
        GCSS["globals.css"]:::server
        RL["layout.tsx"]:::server
        MP["page.tsx"]:::server
        SW["sessionWrapper.tsx"]:::server
        AR["/api/auth Route"]:::server
        ER["/api/events Route"]:::server
        WR["/api/weather Route"]:::server
        NR["/api/news Route"]:::server
        GR["/api/gemini Route"]:::server
    end

    %% External Services
    subgraph "External Services"
        OP["OAuth Provider"]:::external
        CA["Google Calendar API"]:::external
        WA["Weather API"]:::external
        NA["News API"]:::external
        GA["Google Gemini API"]:::external
    end

    %% UI Composition
    RL -->|wraps| SW
    SW -->|renders| MP
    MP --> CW
    MP --> WW
    MP --> NW
    MP --> ClW
    MP --> VCW
    MP --> SB
    MP --> HD

    %% Authentication Flow
    SB -->|"click SignIn"| AR
    AR -->|"OAuth Flow"| OP
    AR -->|"set session cookie"| SW

    %% Calendar Data Flow
    CW -->|"HTTPS GET events"| ER
    ER -->|"fetch events"| CA
    ER -->|"return JSON"| CW

    %% Weather Data Flow
    WW -->|"HTTPS GET weather"| WR
    WR -->|"fetch weather"| WA
    WR -->|"return JSON"| WW

    %% News Data Flow
    NW -->|"HTTPS GET news"| NR
    NR -->|"fetch news"| NA
    NR -->|"return JSON"| NW

    %% Clock Widget (client-side)
    ClW -->|"local update"| ClW

    %% Voice Assistant Flow
    VCW -->|"Transcript POST"| GR:::voice
    GR -->|"proxy request"| GA:::voice
    GA -->|"AI response"| GR:::voice
    GR -->|"return JSON"| VCW

    %% Click Events
    click CW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/CalendarWidget.tsx"
    click WW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/WeatherWidget.tsx"
    click NW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/NewsWidget.tsx"
    click ClW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/ClockWidget.tsx"
    click VCW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/VoiceChatWidget.tsx"
    click HD "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/Header.tsx"
    click SB "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/components/signInButtons.tsx"

    click GCSS "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/globals.css"
    click RL "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/layout.tsx"
    click MP "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/page.tsx"
    click SW "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/sessionWrapper.tsx"

    click AR "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/api/auth/[...nextauth]/route.ts"
    click ER "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/api/events/route.ts"
    click WR "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/api/weather/route.ts"
    click NR "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/api/news/route.ts"
    click GR "https://github.com/thehalfbldprinc3/smartmirror/blob/main/smart-mirror/app/api/gemini/route.ts"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef server fill:#DFF2D8,stroke:#28a745,color:#155724
    classDef external fill:#F0F0F0,stroke:#6c757d,color:#343a40
    classDef voice stroke:#FF8C00,stroke-width:2px,color:#FF8C00
```
