How gnehs/home-dashboard works
1. What this repo is
- A Next.js App Router service that renders server-generated dashboard images for an e-paper / electronic ink display use case.
- The app is not primarily a traditional interactive web UI; its core product is a set of HTTP image endpoints.
2. Main request flow
- A device or browser requests one of the image routes under app/img/....
- The route handler gathers live data from local utilities and external APIs.
- The route returns a rendered image response, suitable for an ESPHome-driven display or any client that can fetch an image URL.
3. Image endpoints
- Each dashboard variant lives in its own route folder:
- app/img/board-1/route.tsx
- app/img/currency/route.tsx
- app/img/currency-2/route.tsx
- app/img/day-clock/route.tsx
- app/img/weather/route.tsx
- This structure makes each dashboard an independently addressable image source with its own layout and data requirements.
4. Rendering subsystem
- utils/ImageResponse.ts and utils/font.ts are the shared rendering layer.
- These utilities likely wrap Next.js image generation primitives and provide consistent fonts/layout behavior across all routes.
- app/globals.css and Tailwind config provide the visual styling foundation used by the rendered image compositions.
5. Data integration layer
- The utils/ directory contains the external-data adapters:
- utils/met-weather.ts for weather
- utils/cryptocompare.ts for crypto pricing
- utils/taifex.ts for Taiwan futures market data
- utils/homeAssistant.ts for Home Assistant entity/state data
- utils/stepStep.ts for StepStep service data
- utils/bot-bank.ts for bank/account-related data
- These modules form the main boundary between the dashboard renderer and outside services.
6. Dashboard-specific composition
- The “board” image (board-1) is the most integration-heavy dashboard and combines home automation / status data.
- The currency dashboards focus on market data.
- The weather dashboard is centered on location-based forecast data.
- The day clock dashboard is likely mostly self-contained, relying on time and formatting rather than external services.
7. Error handling
- app/components/Error.tsx is the shared failure-state component.
- This is important because some routes depend on API connectivity and environment configuration; when those dependencies fail, the image still needs a controlled fallback instead of breaking the render.
8. Configuration and environment
- The app is driven by environment variables declared in .env.example.
- Key config inputs include:
- WEATHER_LAT / WEATHER_LON
- NEXT_PUBLIC_INVERT_COLOR
- Home Assistant host/token
- StepStep host/token
- This means the runtime is highly environment-dependent, especially for dashboards that pull live home data.
9. Consumer boundary
- esphome.lilyt5.example.yaml shows the downstream integration point: an ESPHome device that fetches the rendered images and displays them on an e-paper panel.
- So the architecture includes both the Next.js render service and a separate hardware/display consumer.
10. Deployment and delivery
- Dockerfile packages the app for container deployment.
- .github/workflows/build.yaml automates Docker image builds on GitHub Actions.
- The README indicates images are published to a container registry and then run via docker run, making the deployment model “build container, serve image endpoints, point device at them.”
11. Public/static assets
- public/ holds static files such as robots.txt and referenced preview images.
- app/img/* is the runtime image surface, while public/ is supporting static content.
12. Overall architecture in one line
- This repository is a server-side image rendering backend composed of Next.js route handlers + shared image utilities + external data adapters + containerized deployment, with ESPHome/e-paper devices as the primary consumers.
Main entry points: board-1/route.tsx Board image · page.tsx Landing · currency/route.tsx Currency image · weather/route.tsx Weather image
Components 22
Image service
Next.js app router surfaces that generate dashboard images.
- Landing · Top-level app entry and navigation surface.
app/page.tsx - Root shell · App-wide HTML/layout wrapper and metadata boundary.
app/layout.tsx - Board image · Integration-heavy dashboard image combining home and status data.
app/img/board-1/route.tsx - Currency image · Dashboard image focused on market and exchange-rate data.
app/img/currency/route.tsx - Currency alt · Second currency dashboard variant with a different composition.
app/img/currency-2/route.tsx - Day clock · Self-contained clock/date dashboard image.
app/img/day-clock/route.tsx - Weather image · Location-based weather dashboard image.
app/img/weather/route.tsx - Error card · Fallback failure state used when data sources or config are unavailable.
app/components/Error.tsx - Global styles · Shared CSS foundation for rendered image compositions.
app/globals.css - Tailwind config · Utility-first styling configuration used across the app.
tailwind.config.ts
Rendering and data
Shared image rendering layer and external data adapters.
- Image response · Shared wrapper around Next image generation response primitives.
utils/ImageResponse.ts - Font setup · Shared font loading and typography configuration for image rendering.
utils/font.ts - Met weather · External weather data adapter used by weather-oriented routes.
utils/met-weather.ts - Crypto compare · Crypto pricing adapter for currency dashboards.
utils/cryptocompare.ts - Taifex · Taiwan futures market data adapter.
utils/taifex.ts - Home Assistant · Entity and state data adapter for smart-home dashboards.
utils/homeAssistant.ts - StepStep · StepStep service data adapter used by the board dashboard.
utils/stepStep.ts - Bank data · Bank or account-related data adapter used by the board dashboard.
utils/bot-bank.ts
Delivery
Container and automation for building and running the service.
- Env example · Documented runtime configuration for weather, home automation, and display settings.
.env.example - Dockerfile · Container image definition for deployment.
Dockerfile - Build workflow · GitHub Actions workflow that builds and publishes the container image.
.github/workflows/build.yaml
Consumer
Downstream e-paper display integration.
- ESPHome display · Example e-paper device configuration that fetches the generated images.
esphome.lilyt5.example.yaml
Connections 32
- Landing → Board image: links to · Landing page points users toward the available image endpoints.
- Landing → Currency image: links to · Landing page points users toward the available image endpoints.
- Landing → Currency alt: links to · Landing page points users toward the available image endpoints.
- Landing → Day clock: links to · Landing page points users toward the available image endpoints.
- Landing → Weather image: links to · Landing page points users toward the available image endpoints.
- Board image → Image response: renders via · Board image is returned through the shared image response wrapper.
- Board image → Font setup: uses · Board image shares the common font setup.
- Board image → Home Assistant: reads · Board image pulls home automation state.
- Board image → StepStep: reads · Board image pulls StepStep service data.
- Board image → Bank data: reads · Board image pulls bank/account data.
- Board image → Error card: falls back to · Shared failure component for data or config issues.
- Currency image → Image response: renders via · Currency image is returned through the shared image response wrapper.
- Currency image → Font setup: uses · Currency image shares the common font setup.
- Currency image → Crypto compare: reads · Currency image pulls crypto pricing data.
- Currency image → Taifex: reads · Currency image pulls futures market data.
- Currency alt → Image response: renders via · Currency variant is returned through the shared image response wrapper.
- Currency alt → Font setup: uses · Currency variant shares the common font setup.
- Currency alt → Crypto compare: reads · Currency variant pulls crypto pricing data.
- Day clock → Image response: renders via · Clock image is returned through the shared image response wrapper.
- Day clock → Font setup: uses · Clock image shares the common font setup.
- Weather image → Image response: renders via · Weather image is returned through the shared image response wrapper.
- Weather image → Font setup: uses · Weather image shares the common font setup.
- Weather image → Met weather: reads · Weather image pulls forecast and location data.
- Root shell → Global styles: includes · Root layout applies the global stylesheet.
- Root shell → Tailwind config: styled by · Layout and routes rely on the Tailwind configuration.
- Env example → Met weather: configures · Weather latitude and longitude come from environment settings.
- Env example → Home Assistant: configures · Home Assistant host and token are environment-driven.
- Env example → StepStep: configures · StepStep host and token are environment-driven.
- Env example → Board image: configures · Dashboard behavior depends on runtime environment variables.
- Dockerfile → Build workflow: built by · The Docker image is assembled and published by CI.
- ESPHome display → Board image: fetches · ESPHome device consumes the board image endpoint.
- ESPHome display → Weather image: fetches · ESPHome device can consume weather image endpoints.