How pawelmalak/flame works
Flame is a two-tier self-hosted “start page” application: a Node.js/Express backend serves a React/Redux TypeScript frontend, and the backend owns persistence, authentication, and all integrations. The frontend is a UI shell for managing apps, bookmarks, themes, settings, and weather; the backend exposes REST endpoints and stores data in a local SQLite database through Sequelize.
The frontend lives under client/ and is structured as a feature/component tree rather than a monolith. Major user-facing areas are Home, Apps, Bookmarks, Settings, SearchBar, NotificationCenter, and Widgets. Shared UI primitives live under client/src/components/UI, while feature modules compose those primitives into cards, tables, forms, and modals. State is managed centrally in client/src/store with actions, reducers, and async action-creators for apps, bookmarks, auth, config, themes, and notifications.
The frontend data flow is conventional Redux: components dispatch actions, action-creators call the backend API, reducers update the store, and UI components render from store state. Route protection is handled by ProtectedRoute, and app startup is anchored by client/src/index.tsx and App.tsx. The client also includes utility code for parsing search queries, decoding tokens, redirect URLs, theme parsing, and local UI configuration storage.
The backend is organized by domain under controllers/ and routes/. Each domain has a route module that binds HTTP paths to controller functions: apps, bookmarks, categories, config, queries, themes, weather, and auth. This separation matters architecturally because the routes are thin and the controllers own the business logic and data mutation rules.
Persistence is managed through Sequelize models in models/ and migrations in db/migrations. The main entities are App, Bookmark, Category, Config, and Weather, with model associations centralized in associateModels.js. Migrations show that the schema evolved for config changes, resource access, weather, bookmark ordering, and app descriptions. The database is initialized and backed up via utilities under db/utils and utils/init.
Authentication is a first-class boundary. The backend has auth controllers plus middleware such as requireAuth, auth, and validate, and the frontend has corresponding auth actions and route protection. The README indicates a password-based setup, with support for environment variables and Docker secrets, so authentication is part of the deployment contract rather than an afterthought.
The main content domains are Apps and Bookmarks. Both support CRUD, reordering, and single-item fetches, and both are surfaced through multiple UI modes such as cards, grids, and tables. Categories exist as a separate domain for bookmarks, with their own CRUD and ordering. This implies the app organizes user content hierarchically and allows the home screen to be customized by ordering and pinning.
Search is implemented primarily on the client side as an integrated bar that can filter local apps/bookmarks or redirect to external providers via search prefixes. Search behavior is supported by utility functions and bundled query metadata in searchQueries.json, so the UI can map user input to internal filtering or external navigation without requiring a backend search service.
Weather is a distinct subsystem with both server and client parts. The backend stores weather configuration/data and has endpoints for getting and updating weather, while the frontend renders a WeatherWidget and weather settings. The README makes clear that the app calls an external weather API using user-provided location and API key, so weather is an external integration with periodic refresh rather than static content.
Theme and styling are also managed as a first-class feature. The backend exposes theme and CSS config endpoints, and the frontend contains a theme builder, theme grid, preview, and style settings. Custom CSS, built-in themes, and theme creation are part of the product architecture because they influence rendering globally, not just component-level styling.
Docker and Kubernetes are important deployment/integration boundaries. The repository includes Dockerfiles, docker-compose, multi-arch build support, Kubernetes manifests, and Skaffold configuration. The app can also ingest runtime metadata from Docker containers or Kubernetes ingresses to auto-create apps, which means the backend can act as a discovery layer over external orchestration systems when those integrations are enabled.
Cross-cutting concerns are centralized in middleware/ and utils/. Middleware covers async error handling, request validation, file upload handling, and auth enforcement. Utilities cover token signing/decoding, logging, file helpers, URL and input parsing, theme normalization, weather data cleanup, and app initialization. This keeps controllers focused on domain logic while shared concerns stay reusable.
For an architecture diagram, the main boundaries to show are: browser UI; API server; SQLite persistence; optional external services for weather, Docker, and Kubernetes; and the deployment layer that packages everything in containers. The most important internal flows are UI actions to REST controllers, controllers to Sequelize models/database, and scheduled or on-demand syncs for weather and container/ingress discovery.
Main entry points: App.tsx App shell · index.js Controllers · store.ts Redux store · server.js API server
Components 24
Frontend
React/Redux client for home, content management, settings, search, and widgets.
- Client entry · Application startup and routing shell for the browser UI.
client/src/index.tsx - App shell · Top-level client layout, route wiring, and protected navigation.
client/src/App.tsx - Home · Home screen with header and combined overview of content.
client/src/components/Home/Home.tsx - Apps UI · Client-side apps management across cards, grid, table, and forms.
client/src/components/Apps/Apps.tsx - Bookmarks UI · Client-side bookmark and category management surface.
client/src/components/Bookmarks/Bookmarks.tsx - Settings UI · Client-side settings hub for general, style, weather, Docker, and auth.
client/src/components/Settings/Settings.tsx - Search bar · Integrated search and redirect entry for local filtering and external providers.
client/src/components/SearchBar/SearchBar.tsx - Notifications · Notification center and toast-style user feedback handling.
client/src/components/NotificationCenter/NotificationCenter.tsx - Weather widget · Home widget that renders current weather state.
client/src/components/Widgets/WeatherWidget/WeatherWidget.tsx - Protected route · Client-side access control for authenticated views.
client/src/components/Routing/ProtectedRoute.tsx - Redux store · Centralized client state container and reducer composition.
client/src/store/store.ts - Action creators · Client-side async dispatchers that call the backend API.
client/src/store/action-creators/index.ts - Reducers · State update logic for apps, bookmarks, auth, config, themes, and notifications.
client/src/store/reducers/index.ts - Client utils · Search, token, theme, redirect, and local UI config helpers.
client/src/utility/index.ts
Backend
Express API, domain controllers, middleware, and runtime jobs.
- API server · Backend HTTP entrypoint and application bootstrap.
server.js - Routes · Thin route bindings for domain endpoints.
routes/apps.js - Controllers · Business logic for apps, bookmarks, categories, config, queries, themes, weather, and auth.
controllers/apps/index.js - Middleware · Async handling, auth enforcement, validation, uploads, and error handling.
middleware/index.js
Persistence
SQLite schema, Sequelize models, and database utilities.
- Models · Core entities and associations for persisted application data.
models/associateModels.js - Migrations · Database migration history for config, resources, weather, ordering, and descriptions.
db/migrations/00_initial.js - DB utils · Database initialization and backup utilities.
db/utils/backupDb.js
Deployment
Container and Kubernetes packaging for self-hosted runs.
- Deployment · Docker, Compose, Kubernetes, and Skaffold deployment assets.
.docker/docker-compose.yml
External services
Optional integrations consumed by the backend or discovery sync.
- Weather API · Third-party weather service consumed by backend weather integration.
utils/getExternalWeather.js - Docker/K8s discovery · Optional runtime discovery of containers and Kubernetes ingresses for auto-created apps.
controllers/apps/docker/index.js
Connections 28
- Client entry → App shell: boots · Browser startup mounts the top-level app shell.
- App shell → Protected route: protects · Authenticated areas are wrapped by route protection.
- App shell → Home: renders · Shell routes to the home screen.
- App shell → Apps UI: routes · Shell exposes the apps management view.
- App shell → Bookmarks UI: routes · Shell exposes the bookmarks management view.
- App shell → Settings UI: routes · Shell exposes the settings hub.
- Home → Search bar: uses · Home integrates the search bar for quick navigation.
- Home → Weather widget: shows · Home surface includes the weather widget.
- Apps UI → Redux store: reads · Apps view renders from central Redux state.
- Bookmarks UI → Redux store: reads · Bookmarks view renders from central Redux state.
- Settings UI → Redux store: reads · Settings view renders from central Redux state.
- Notifications → Redux store: reads · Notification center reflects store state.
- Redux store → Action creators: dispatches · UI actions flow into async action creators.
- Action creators → Reducers: updates · Async results are reduced into next client state.
- Action creators → API server: calls · Client action creators talk to backend REST endpoints.
- Client utils → Search bar: supports · Search parsing and redirect helpers back the search UI.
- Client utils → Settings UI: supports · Local config and theme helpers back settings flows.
- API server → Routes: mounts · Server mounts domain route modules.
- Routes → Controllers: delegates · Routes stay thin and delegate to controller logic.
- Controllers → Middleware: uses · Controllers are wrapped by auth, validation, and async helpers.
- Controllers → Models: mutates · Domain logic reads and writes persistent entities.
- Models → Migrations: evolves from · Migrations define and evolve the SQLite schema.
- Models → DB utils: managed by · Database setup and backup utilities operate around the models.
- Controllers → Weather API: fetches · Weather controller integrates with the external weather API.
- Controllers → Docker/K8s discovery: discovers · App controllers can ingest Docker or Kubernetes runtime metadata.
- API server → Deployment: packaged by · The server is packaged through container and cluster manifests.
- Deployment → Docker/K8s discovery: enables · Deployment options support discovery and runtime integrations.
- API server → Models: persists · Server-side domain operations ultimately persist in SQLite.