# thomasmarren/smart-display architecture

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

- Interactive diagram: https://gitdiagram.com/thomasmarren/smart-display
- Repository: https://github.com/thomasmarren/smart-display

## Overview

##### Main Components
- Frontend (Next.js React UI)
– Pages & Components
– Context Providers & Hooks
- Backend (Next.js API Routes + Server-Side Rendering)
– API route handlers in src/pages/api
– Controller, Route Handler, Prisma config
- Database
– Prisma ORM layer
– SQLite file (prisma/schema.prisma + migrations)
- External Services & APIs
– Google Photos API
– Spotify API
– Ecobee API
– Open-Meteo (Weather)
– Public Holidays API (used by holidays widget)

##### Relationships & Data Flows
- Browser ↔ Next.js Frontend
– User opens the “display” page or other widget pages
– React components hydrate in the browser, some data fetched client-side
- Frontend ↔ Next.js API Routes (Serverless Functions)
– Client-side data fetching hooks (e.g., usePhotos, useSpotify) call `/api/photos`, `/api/spotify`, etc.
– Server-side data fetching (getServerSideProps) may invoke API endpoints as well
- API Routes ↔ External Clients
– Handler imports client modules (src/clients/googlePhotos.ts, googleCalendar.ts, etc.)
– They perform OAuth, token refresh, HTTP calls to third-party APIs
- API Routes ↔ Database
– The controller/routeHandler layer uses Prisma client (src/config/prisma.ts)
– Session or token data (e.g., next_page_token) is read/written to SQLite
- Context & State Management
– WidgetProvider (src/contexts/WidgetProvider.tsx) aggregates data from multiple hooks
– Provides a unified data context for UI components

##### Architectural Patterns & Design Principles
- Separation of Concerns
– UI components in src/components, business logic in hooks/services, data layer in Prisma
- Serverless API Layer
– Next.js API routes are individually deployable serverless functions
- React Context + Custom Hooks
– Encapsulate data-fetching logic and state management for each widget
- ORM Migration-Based Schema
– Prisma migrations folder documents schema evolution; ensures versioned DB schema

##### Relevant Technologies & Frameworks
- Next.js (Pages folder for routing, API routes for back end)
- React & TypeScript (components, hooks, contexts)
- Prisma + SQLite (ORM + file-based database)
- OAuth 2.0 flows with Google, Spotify, Ecobee
- External REST APIs: Open-Meteo, Public Holidays service
- Vercel deployment configuration (vercel.json)

##### Final Checklist
– Annotate key technologies (Next.js, React, Prisma, SQLite, OAuth providers)
– Ensure the OAuth handshake, database migrations, and widget update loops are represented

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Client Layer
    subgraph "Browser/Client Layer"
        direction TB
        DisplayPage["display/index.tsx"]:::frontend
        HomePage["index.tsx"]:::frontend
        SpotifyPage["spotify/index.tsx"]:::frontend
        EcobeePage["ecobee/index.tsx"]:::frontend
        GoogleAuthPage["google_auth/index.tsx"]:::frontend
        GoogleCallbackPage["google_callback/index.tsx"]:::frontend
        SpotifyCallbackPage["spotify_callback/index.tsx"]:::frontend
        HelloPage["hello/index.tsx"]:::frontend

        subgraph "UI Components"
            direction TB
            DisplayComp["Display.tsx"]:::frontend
            Marquee["Marquee.tsx"]:::frontend
            SleepComp["Sleep.tsx"]:::frontend
            SpotifyComp["Spotify/index.tsx"]:::frontend
            ClockComp["Time/Clock.tsx"]:::frontend
            TimeComp["Time/index.tsx"]:::frontend
            WeatherComp["Weather/index.tsx"]:::frontend
            WeatherIcons["Weather/icons.tsx"]:::frontend
        end

        WidgetProvider["WidgetProvider.tsx"]:::frontend

        subgraph "Custom Hooks"
            direction TB
            usePhotos["usePhotos.ts"]:::frontend
            useSpotify["useSpotify.ts"]:::frontend
            useWeather["useWeather.ts"]:::frontend
            useEcobee["useEcobee.ts"]:::frontend
            useHolidays["useHolidays.ts"]:::frontend
            useEvery["useEvery.ts"]:::frontend
            useAuth["useIsAuthenticated.ts"]:::frontend
        end
    end

    %% Next.js Server / API Layer
    subgraph "Next.js Server / API Layer"
        direction TB
        subgraph "API Routes"
            direction TB
            APIPhotos["api/photos.ts"]:::backend
            APISpotify["api/spotify.ts"]:::backend
            APISpotifyAuth["api/spotify_auth.ts"]:::backend
            APIGoogleAuth["api/google_auth.ts"]:::backend
            APIGoogleCallback["api/google_callback.ts"]:::backend
            APIEcobee["api/ecobee.ts"]:::backend
            APIEcobeeAuth["api/ecobee_auth.ts"]:::backend
            APICalendar["api/calendar.ts"]:::backend
            APIHolidays["api/holidays.ts"]:::backend
            APIStocks["api/stocks.ts"]:::backend
            APIAlbums["api/albums.ts"]:::backend
            APITypes["api/types.ts"]:::backend
        end
        Controller["controller.ts / routeHandler.ts"]:::backend
        PrismaClient["prisma.ts"]:::backend
    end

    %% Database & External Services
    subgraph "Database & Externals"
        direction TB
        DB["prisma/schema.prisma"]:::db
        Migrations["prisma/migrations"]:::db
        subgraph "External Services"
            direction TB
            GooglePhotosAPI["Google Photos API"]:::external
            SpotifyAPI["Spotify API"]:::external
            EcobeeAPI["Ecobee API"]:::external
            WeatherAPI["Open-Meteo API"]:::external
            HolidaysAPI["Public Holidays API"]:::external
        end
    end

    %% Connections
    DisplayPage -->|renders| DisplayComp
    DisplayPage -->|uses| WidgetProvider
    WidgetProvider -->|aggregates| usePhotos
    WidgetProvider -->|aggregates| useSpotify
    WidgetProvider -->|aggregates| useWeather
    WidgetProvider -->|aggregates| useEcobee
    WidgetProvider -->|aggregates| useHolidays

    DisplayComp -->|calls| useEvery
    DisplayComp -->|calls| useAuth
    DisplayComp -->|renders| Marquee & SleepComp & SpotifyComp & ClockComp & TimeComp & WeatherComp

    usePhotos -->|fetch| APIPhotos
    useSpotify -->|fetch| APISpotify
    useWeather -->|fetch| APICalendar & APIHolidays
    useEcobee -->|fetch| APIEcobee
    useHolidays -->|fetch| APIHolidays

    APIPhotos -->|calls| Controller
    APISpotify -->|calls| Controller
    APIGoogleAuth -->|redirect| GooglePhotosAPI
    APIGoogleCallback -->|callback| Controller
    APIEcobeeAuth -->|redirect| EcobeeAPI
    APIEcobee -->|HTTP| EcobeeAPI
    APISpotifyAuth -->|redirect| SpotifyAPI

    Controller -->|uses| PrismaClient
    PrismaClient -->|reads/writes| DB
    Controller -->|calls| GooglePhotosAPI & SpotifyAPI & EcobeeAPI & WeatherAPI & HolidaysAPI

    GooglePhotosAPI -->|response| APIPhotos
    SpotifyAPI -->|response| APISpotify
    EcobeeAPI -->|response| APIEcobee
    WeatherAPI -->|response| APIWeather
    HolidaysAPI -->|response| APIHolidays

    %% Click Events
    click DisplayPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/display/index.tsx"
    click HomePage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/index.tsx"
    click SpotifyPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/spotify/index.tsx"
    click EcobeePage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/ecobee/index.tsx"
    click GoogleAuthPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/google_auth/index.tsx"
    click GoogleCallbackPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/google_callback/index.tsx"
    click SpotifyCallbackPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/spotify_callback/index.tsx"
    click HelloPage "https://github.com/thomasmarren/smart-display/blob/main/src/pages/hello/index.tsx"

    click DisplayComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Display.tsx"
    click Marquee "https://github.com/thomasmarren/smart-display/blob/main/src/components/Marquee.tsx"
    click SleepComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Sleep.tsx"
    click SpotifyComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Spotify/index.tsx"
    click ClockComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Time/Clock.tsx"
    click TimeComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Time/index.tsx"
    click WeatherComp "https://github.com/thomasmarren/smart-display/blob/main/src/components/Weather/index.tsx"
    click WeatherIcons "https://github.com/thomasmarren/smart-display/blob/main/src/components/Weather/icons.tsx"

    click WidgetProvider "https://github.com/thomasmarren/smart-display/blob/main/src/contexts/WidgetProvider.tsx"

    click usePhotos "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/usePhotos.ts"
    click useSpotify "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useSpotify.ts"
    click useWeather "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useWeather.ts"
    click useEcobee "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useEcobee.ts"
    click useHolidays "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useHolidays.ts"
    click useEvery "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useEvery.ts"
    click useAuth "https://github.com/thomasmarren/smart-display/blob/main/src/hooks/useIsAuthenticated.ts"

    click APIPhotos "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/photos.ts"
    click APISpotify "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/spotify.ts"
    click APISpotifyAuth "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/spotify_auth.ts"
    click APIGoogleAuth "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/google_auth.ts"
    click APIGoogleCallback "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/google_callback.ts"
    click APIEcobee "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/ecobee.ts"
    click APIEcobeeAuth "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/ecobee_auth.ts"
    click APICalendar "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/calendar.ts"
    click APIHolidays "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/holidays.ts"
    click APIStocks "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/stocks.ts"
    click APIAlbums "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/albums.ts"
    click APITypes "https://github.com/thomasmarren/smart-display/blob/main/src/pages/api/types.ts"

    click Controller "https://github.com/thomasmarren/smart-display/blob/main/src/config/controller.ts"
    click PrismaClient "https://github.com/thomasmarren/smart-display/blob/main/src/config/prisma.ts"

    click DB "https://github.com/thomasmarren/smart-display/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/thomasmarren/smart-display/tree/main/prisma/migrations"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E0FFD8,stroke:#28A745,color:#28A745
    classDef db fill:#F0F0F0,stroke:#666666,color:#333333
    classDef external fill:#FFF5D1,stroke:#DAA520,color:#DAA520
```
