# framerrr/framerr architecture

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

- Interactive diagram: https://gitdiagram.com/framerrr/framerr
- Repository: https://github.com/framerrr/framerr

## Overview

Framerr is a self-hosted homelab dashboard. Users authenticate, configure integrations and dashboards, then view embedded tabs and live widgets; administrators can also share layouts, manage notifications, and customize the experience. The browser app communicates through a centralized API client with an Express server, whose routes use database-backed services. Realtime updates use SSE, while integration adapters connect the product to homelab services. The graph reflects README capabilities and the supplied source index/excerpts; several feature implementations were not sampled, so undocumented connections are omitted.

Main entry points: [`server/routes`](https://github.com/framerrr/framerr/tree/main/server/routes) (HTTP route handlers), [`src/App.tsx`](https://github.com/framerrr/framerr/blob/main/src/App.tsx) (React application), [`server/integrations`](https://github.com/framerrr/framerr/tree/main/server/integrations) (Integration adapters), [`src/api/client.ts`](https://github.com/framerrr/framerr/blob/main/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webapp["React application<br/>[App.tsx]"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_customize["Themes and settings"]
end

subgraph group_platform["Application platform"]
  node_api["API client<br/>[client.ts]"]
  node_server["Express application<br/>[app.ts]"]
  node_routes["HTTP route handlers"]
  node_database[("SQLite persistence<br/>[db.ts]")]
end

subgraph group_domain["Dashboard capabilities"]
  node_dashboard["Dashboards and widgets"]
  node_iframe["Iframe tabs"]
  node_notifications["Notifications and push<br/>[notifications.ts]"]
  node_templates["Dashboard templates"]
  node_sharing["User and resource sharing<br/>[widgetShares.ts]"]
end

subgraph group_operations["Service operations"]
  node_integrations["Integration adapters"]
  node_poller["Integration polling<br/>[servicePoller.ts]"]
  node_realtime["SSE delivery"]
end

node_user(("Dashboard user"))
node_external{{"Homelab services"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"provides auth"| node_auth
node_webapp -->|"renders"| node_dashboard
node_webapp -->|"renders"| node_iframe
node_webapp -->|"offers settings"| node_customize
node_dashboard -.->|"requests data"| node_api
node_customize -.->|"saves settings"| node_api
node_api -.->|"sends requests"| node_server
node_server -->|"registers routes"| node_routes
node_routes -.->|"persists data"| node_database
node_routes -.->|"proxies service requests"| node_integrations
node_external -.->|"serves integration data"| node_integrations
node_poller -.->|"polls services"| node_integrations
node_integrations -.->|"supplies live updates"| node_realtime
node_realtime -->|"streams updates"| node_webapp
node_routes -.->|"handles alerts"| node_notifications
node_routes -.->|"handles layouts"| node_templates
node_routes -.->|"handles access"| node_sharing

click node_webapp "https://github.com/framerrr/framerr/blob/main/src/App.tsx"
click node_auth "https://github.com/framerrr/framerr/blob/main/src/context/AuthContext.tsx"
click node_dashboard "https://github.com/framerrr/framerr/tree/main/src/app/dashboard"
click node_iframe "https://github.com/framerrr/framerr/tree/main/src/app/tabs"
click node_customize "https://github.com/framerrr/framerr/tree/main/src/settings/customization"
click node_api "https://github.com/framerrr/framerr/blob/main/src/api/client.ts"
click node_server "https://github.com/framerrr/framerr/blob/main/server/app.ts"
click node_routes "https://github.com/framerrr/framerr/tree/main/server/routes"
click node_database "https://github.com/framerrr/framerr/blob/main/server/database/db.ts"
click node_integrations "https://github.com/framerrr/framerr/tree/main/server/integrations"
click node_poller "https://github.com/framerrr/framerr/blob/main/server/services/servicePoller.ts"
click node_realtime "https://github.com/framerrr/framerr/tree/main/server/services/sse"
click node_notifications "https://github.com/framerrr/framerr/blob/main/server/routes/notifications.ts"
click node_templates "https://github.com/framerrr/framerr/tree/main/server/routes/templates"
click node_sharing "https://github.com/framerrr/framerr/blob/main/server/routes/widgetShares.ts"

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_webapp,node_auth,node_customize,node_user toneBlue
class node_api,node_server,node_routes,node_database toneAmber
class node_dashboard,node_iframe,node_notifications,node_templates,node_sharing toneMint
class node_integrations,node_poller,node_realtime toneRose
class node_external toneIndigo
```

## Components

### User experience

- [React application](https://github.com/framerrr/framerr/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/framerrr/framerr/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Themes and settings](https://github.com/framerrr/framerr/tree/main/src/settings/customization): `src/settings/customization`

### Application platform

- [API client](https://github.com/framerrr/framerr/blob/main/src/api/client.ts): `src/api/client.ts`
- [Express application](https://github.com/framerrr/framerr/blob/main/server/app.ts): `server/app.ts`
- [HTTP route handlers](https://github.com/framerrr/framerr/tree/main/server/routes): `server/routes`
- [SQLite persistence](https://github.com/framerrr/framerr/blob/main/server/database/db.ts): `server/database/db.ts`

### Dashboard capabilities

- [Dashboards and widgets](https://github.com/framerrr/framerr/tree/main/src/app/dashboard): `src/app/dashboard`
- [Iframe tabs](https://github.com/framerrr/framerr/tree/main/src/app/tabs): `src/app/tabs`
- [Notifications and push](https://github.com/framerrr/framerr/blob/main/server/routes/notifications.ts): `server/routes/notifications.ts`
- [Dashboard templates](https://github.com/framerrr/framerr/tree/main/server/routes/templates): `server/routes/templates`
- [User and resource sharing](https://github.com/framerrr/framerr/blob/main/server/routes/widgetShares.ts): `server/routes/widgetShares.ts`

### Service operations

- [Integration adapters](https://github.com/framerrr/framerr/tree/main/server/integrations): `server/integrations`
- [Integration polling](https://github.com/framerrr/framerr/blob/main/server/services/servicePoller.ts): `server/services/servicePoller.ts`
- [SSE delivery](https://github.com/framerrr/framerr/tree/main/server/services/sse): `server/services/sse`

### Other components

- **Dashboard user**
- **Homelab services**

## Connections

- Dashboard user → React application: uses (evidence: `README.md`)
- React application → Authentication: provides auth (evidence: `src/App.tsx`)
- React application → Dashboards and widgets: renders (evidence: `src/App.tsx`)
- React application → Iframe tabs: renders (evidence: `README.md`)
- React application → Themes and settings: offers settings (evidence: `README.md`)
- Dashboards and widgets → API client: requests data
- Themes and settings → API client: saves settings
- API client → Express application: sends requests
- Express application → HTTP route handlers: registers routes (evidence: `server/app.ts`)
- HTTP route handlers → SQLite persistence: persists data
- HTTP route handlers → Integration adapters: proxies service requests
- Homelab services → Integration adapters: serves integration data (evidence: `README.md`)
- Integration polling → Integration adapters: polls services
- Integration adapters → SSE delivery: supplies live updates
- SSE delivery → React application: streams updates
- HTTP route handlers → Notifications and push: handles alerts
- HTTP route handlers → Dashboard templates: handles layouts
- HTTP route handlers → User and resource sharing: handles access
