How thomasmarren/smart-display works
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