# pawelmalak/flame architecture

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

- Interactive diagram: https://gitdiagram.com/pawelmalak/flame
- Repository: https://github.com/pawelmalak/flame

## Overview

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: [`client/src/App.tsx`](https://github.com/pawelmalak/flame/blob/master/client/src/App.tsx) (App shell), [`controllers/apps/index.js`](https://github.com/pawelmalak/flame/blob/master/controllers/apps/index.js) (Controllers), [`client/src/store/store.ts`](https://github.com/pawelmalak/flame/blob/master/client/src/store/store.ts) (Redux store), [`server.js`](https://github.com/pawelmalak/flame/blob/master/server.js) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_client_entry["Client entry<br/>React bootstrap<br/>[index.tsx]"]
  node_app_shell["App shell<br/>Root UI<br/>[App.tsx]"]
  node_home["Home<br/>Landing view<br/>[Home.tsx]"]
  node_apps_ui["Apps UI<br/>Feature view<br/>[Apps.tsx]"]
  node_bookmarks_ui["Bookmarks UI<br/>Feature view<br/>[Bookmarks.tsx]"]
  node_settings_ui["Settings UI<br/>Feature view<br/>[Settings.tsx]"]
  node_search_bar["Search bar<br/>Search UI<br/>[SearchBar.tsx]"]
  node_notifications["Notifications<br/>UI feedback"]
  node_weather_widget["Weather widget<br/>[WeatherWidget.tsx]"]
  node_route_guard["Protected route<br/>Route guard<br/>[ProtectedRoute.tsx]"]
  node_store[("Redux store<br/>State core<br/>[store.ts]")]
  node_action_creators["Action creators<br/>Async flow<br/>[index.ts]"]
  node_reducers["Reducers<br/>[index.ts]"]
  node_client_utils["Client utils<br/>Parsing/helpers<br/>[index.ts]"]
end

subgraph group_backend["Backend"]
  node_api_server["API server<br/>Express server<br/>[server.js]"]
  node_routes["Routes<br/>HTTP routing<br/>[apps.js]"]
  node_controllers["Controllers<br/>Domain logic<br/>[index.js]"]
  node_middleware["Middleware<br/>Cross-cutting<br/>[index.js]"]
end

subgraph group_data["Persistence"]
  node_models[("Models<br/>[associateModels.js]")]
  node_migrations["Migrations<br/>Schema evolution<br/>[00_initial.js]"]
  node_db_utils["DB utils<br/>Database helpers<br/>[backupDb.js]"]
end

subgraph group_deploy["Deployment"]
  node_deployment["Deployment<br/>Containers/K8s<br/>[docker-compose.yml]"]
end

subgraph group_external["External services"]
  node_weather_ext["Weather API<br/>External API"]
  node_docker_runtime["Docker/K8s discovery<br/>Discovery integration<br/>[index.js]"]
end

node_client_entry -->|"boots"| node_app_shell
node_app_shell -->|"protects"| node_route_guard
node_app_shell -->|"renders"| node_home
node_app_shell -->|"routes"| node_apps_ui
node_app_shell -->|"routes"| node_bookmarks_ui
node_app_shell -->|"routes"| node_settings_ui
node_home -->|"uses"| node_search_bar
node_home -->|"shows"| node_weather_widget
node_apps_ui -->|"reads"| node_store
node_bookmarks_ui -->|"reads"| node_store
node_settings_ui -->|"reads"| node_store
node_notifications -->|"reads"| node_store
node_store -->|"dispatches"| node_action_creators
node_action_creators -->|"updates"| node_reducers
node_action_creators -->|"calls"| node_api_server
node_client_utils -->|"supports"| node_search_bar
node_client_utils -->|"supports"| node_settings_ui
node_api_server -->|"mounts"| node_routes
node_routes -->|"delegates"| node_controllers
node_controllers -->|"uses"| node_middleware
node_controllers -->|"mutates"| node_models
node_models -->|"evolves from"| node_migrations
node_models -->|"managed by"| node_db_utils
node_controllers -->|"fetches"| node_weather_ext
node_controllers -->|"discovers"| node_docker_runtime
node_api_server -->|"packaged by"| node_deployment
node_deployment -.->|"enables"| node_docker_runtime
node_api_server -->|"persists"| node_models

click node_client_entry "https://github.com/pawelmalak/flame/blob/master/client/src/index.tsx"
click node_app_shell "https://github.com/pawelmalak/flame/blob/master/client/src/App.tsx"
click node_home "https://github.com/pawelmalak/flame/blob/master/client/src/components/Home/Home.tsx"
click node_apps_ui "https://github.com/pawelmalak/flame/blob/master/client/src/components/Apps/Apps.tsx"
click node_bookmarks_ui "https://github.com/pawelmalak/flame/blob/master/client/src/components/Bookmarks/Bookmarks.tsx"
click node_settings_ui "https://github.com/pawelmalak/flame/blob/master/client/src/components/Settings/Settings.tsx"
click node_search_bar "https://github.com/pawelmalak/flame/blob/master/client/src/components/SearchBar/SearchBar.tsx"
click node_notifications "https://github.com/pawelmalak/flame/blob/master/client/src/components/NotificationCenter/NotificationCenter.tsx"
click node_weather_widget "https://github.com/pawelmalak/flame/blob/master/client/src/components/Widgets/WeatherWidget/WeatherWidget.tsx"
click node_route_guard "https://github.com/pawelmalak/flame/blob/master/client/src/components/Routing/ProtectedRoute.tsx"
click node_store "https://github.com/pawelmalak/flame/blob/master/client/src/store/store.ts"
click node_action_creators "https://github.com/pawelmalak/flame/blob/master/client/src/store/action-creators/index.ts"
click node_reducers "https://github.com/pawelmalak/flame/blob/master/client/src/store/reducers/index.ts"
click node_client_utils "https://github.com/pawelmalak/flame/blob/master/client/src/utility/index.ts"
click node_api_server "https://github.com/pawelmalak/flame/blob/master/server.js"
click node_routes "https://github.com/pawelmalak/flame/blob/master/routes/apps.js"
click node_controllers "https://github.com/pawelmalak/flame/blob/master/controllers/apps/index.js"
click node_middleware "https://github.com/pawelmalak/flame/blob/master/middleware/index.js"
click node_models "https://github.com/pawelmalak/flame/blob/master/models/associateModels.js"
click node_migrations "https://github.com/pawelmalak/flame/blob/master/db/migrations/00_initial.js"
click node_db_utils "https://github.com/pawelmalak/flame/blob/master/db/utils/backupDb.js"
click node_deployment "https://github.com/pawelmalak/flame/blob/master/.docker/docker-compose.yml"
click node_weather_ext "https://github.com/pawelmalak/flame/blob/master/utils/getExternalWeather.js"
click node_docker_runtime "https://github.com/pawelmalak/flame/blob/master/controllers/apps/docker/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_entry,node_app_shell,node_home,node_apps_ui,node_bookmarks_ui,node_settings_ui,node_search_bar,node_notifications,node_weather_widget,node_route_guard,node_store,node_action_creators,node_reducers,node_client_utils toneBlue
class node_api_server,node_routes,node_controllers,node_middleware toneAmber
class node_models,node_migrations,node_db_utils toneMint
class node_deployment toneRose
class node_weather_ext,node_docker_runtime toneIndigo
```

## Components

### Frontend

React/Redux client for home, content management, settings, search, and widgets.

- [Client entry](https://github.com/pawelmalak/flame/blob/master/client/src/index.tsx): React bootstrap · Application startup and routing shell for the browser UI. · `client/src/index.tsx`
- [App shell](https://github.com/pawelmalak/flame/blob/master/client/src/App.tsx): Root UI · Top-level client layout, route wiring, and protected navigation. · `client/src/App.tsx`
- [Home](https://github.com/pawelmalak/flame/blob/master/client/src/components/Home/Home.tsx): Landing view · Home screen with header and combined overview of content. · `client/src/components/Home/Home.tsx`
- [Apps UI](https://github.com/pawelmalak/flame/blob/master/client/src/components/Apps/Apps.tsx): Feature view · Client-side apps management across cards, grid, table, and forms. · `client/src/components/Apps/Apps.tsx`
- [Bookmarks UI](https://github.com/pawelmalak/flame/blob/master/client/src/components/Bookmarks/Bookmarks.tsx): Feature view · Client-side bookmark and category management surface. · `client/src/components/Bookmarks/Bookmarks.tsx`
- [Settings UI](https://github.com/pawelmalak/flame/blob/master/client/src/components/Settings/Settings.tsx): Feature view · Client-side settings hub for general, style, weather, Docker, and auth. · `client/src/components/Settings/Settings.tsx`
- [Search bar](https://github.com/pawelmalak/flame/blob/master/client/src/components/SearchBar/SearchBar.tsx): Search UI · Integrated search and redirect entry for local filtering and external providers. · `client/src/components/SearchBar/SearchBar.tsx`
- [Notifications](https://github.com/pawelmalak/flame/blob/master/client/src/components/NotificationCenter/NotificationCenter.tsx): UI feedback · Notification center and toast-style user feedback handling. · `client/src/components/NotificationCenter/NotificationCenter.tsx`
- [Weather widget](https://github.com/pawelmalak/flame/blob/master/client/src/components/Widgets/WeatherWidget/WeatherWidget.tsx): Widget · Home widget that renders current weather state. · `client/src/components/Widgets/WeatherWidget/WeatherWidget.tsx`
- [Protected route](https://github.com/pawelmalak/flame/blob/master/client/src/components/Routing/ProtectedRoute.tsx): Route guard · Client-side access control for authenticated views. · `client/src/components/Routing/ProtectedRoute.tsx`
- [Redux store](https://github.com/pawelmalak/flame/blob/master/client/src/store/store.ts): State core · Centralized client state container and reducer composition. · `client/src/store/store.ts`
- [Action creators](https://github.com/pawelmalak/flame/blob/master/client/src/store/action-creators/index.ts): Async flow · Client-side async dispatchers that call the backend API. · `client/src/store/action-creators/index.ts`
- [Reducers](https://github.com/pawelmalak/flame/blob/master/client/src/store/reducers/index.ts): State reducers · State update logic for apps, bookmarks, auth, config, themes, and notifications. · `client/src/store/reducers/index.ts`
- [Client utils](https://github.com/pawelmalak/flame/blob/master/client/src/utility/index.ts): Parsing/helpers · 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](https://github.com/pawelmalak/flame/blob/master/server.js): Express server · Backend HTTP entrypoint and application bootstrap. · `server.js`
- [Routes](https://github.com/pawelmalak/flame/blob/master/routes/apps.js): HTTP routing · Thin route bindings for domain endpoints. · `routes/apps.js`
- [Controllers](https://github.com/pawelmalak/flame/blob/master/controllers/apps/index.js): Domain logic · Business logic for apps, bookmarks, categories, config, queries, themes, weather, and auth. · `controllers/apps/index.js`
- [Middleware](https://github.com/pawelmalak/flame/blob/master/middleware/index.js): Cross-cutting · Async handling, auth enforcement, validation, uploads, and error handling. · `middleware/index.js`

### Persistence

SQLite schema, Sequelize models, and database utilities.

- [Models](https://github.com/pawelmalak/flame/blob/master/models/associateModels.js): Sequelize models · Core entities and associations for persisted application data. · `models/associateModels.js`
- [Migrations](https://github.com/pawelmalak/flame/blob/master/db/migrations/00_initial.js): Schema evolution · Database migration history for config, resources, weather, ordering, and descriptions. · `db/migrations/00_initial.js`
- [DB utils](https://github.com/pawelmalak/flame/blob/master/db/utils/backupDb.js): Database helpers · Database initialization and backup utilities. · `db/utils/backupDb.js`

### Deployment

Container and Kubernetes packaging for self-hosted runs.

- [Deployment](https://github.com/pawelmalak/flame/blob/master/.docker/docker-compose.yml): Containers/K8s · Docker, Compose, Kubernetes, and Skaffold deployment assets. · `.docker/docker-compose.yml`

### External services

Optional integrations consumed by the backend or discovery sync.

- [Weather API](https://github.com/pawelmalak/flame/blob/master/utils/getExternalWeather.js): External API · Third-party weather service consumed by backend weather integration. · `utils/getExternalWeather.js`
- [Docker/K8s discovery](https://github.com/pawelmalak/flame/blob/master/controllers/apps/docker/index.js): Discovery integration · Optional runtime discovery of containers and Kubernetes ingresses for auto-created apps. · `controllers/apps/docker/index.js`

## Connections

- 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.
