# zeidzahouani-lgtm/radiantdisplay-hub architecture

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

- Interactive diagram: https://gitdiagram.com/zeidzahouani-lgtm/radiantdisplay-hub
- Repository: https://github.com/zeidzahouani-lgtm/radiantdisplay-hub

## Overview

1. **Overall shape**
   - This is a **single-page React application** built with **Vite, TypeScript, Tailwind CSS, and shadcn/ui**.
   - The repo is split into a **browser client** (`src`) and a **Supabase backend layer** (`supabase`), with no separate custom API server.

2. **Core domain**
   - The application appears to be a **digital signage / screen management platform**.
   - Main domain objects include **establishments, screens, playlists, schedules, layouts, video walls, media, programs, licenses, users, and notifications**.
   - Most UI and data hooks are organized around those entities.

3. **Client shell and routing**
   - `src/main.tsx`, `App.tsx`, `pages/`, and the shared layout components define the application shell and route-level screens.
   - Pages are split into operational areas such as **Dashboard**, **Displays**, **Playlists**, **Schedules**, **Library**, **Layouts**, **Team**, **Resources**, and several **admin** pages.
   - `DashboardLayout`, `AppSidebar`, and `NavLink` indicate a persistent navigation shell for authenticated users.

4. **Tenant / organization boundary**
   - `EstablishmentContext` and related components such as `EstablishmentSwitcher`, `EstablishmentAssignSelect`, and `EstablishmentDashboard` show that the app is **scoped by establishment**.
   - That establishment boundary is likely the primary isolation layer for data access and UI context.
   - Many hooks are establishment-aware: branding, settings, licenses, screens, playlists, schedules, and notifications.

5. **Data access pattern**
   - Most domain data is accessed through custom hooks in `src/hooks`, such as `useScreens`, `usePlaylists`, `useSchedules`, `useMedia`, `useLayouts`, `useContents`, and `useDashboardStats`.
   - These hooks form the application’s **client-side data layer**, abstracting Supabase queries and realtime subscriptions away from UI components.
   - `useScreenRealtime` suggests some entities update live, likely for screen status or playback state.

6. **Backend and persistence**
   - `src/integrations/supabase/client.ts` and `types.ts` show that **Supabase is the main backend platform**.
   - The `supabase/migrations` folder is the source of truth for the **Postgres schema**, relationships, and likely RLS/security rules.
   - The client likely uses Supabase for **auth, database access, realtime updates, and storage-backed media**.

7. **Operational edge functions**
   - The `supabase/functions` directory contains the app’s privileged backend workflows.
   - Notable functions include **auth/bootstrap** (`bootstrap-admin`), **email/inbox processing** (`check-inbox`, `check-email-replies`, `send-credentials`, `test-email`), **content workflows** (`content-webhook`, `content-action`, `resend-ack`), **AI support** (`ai-assistant`), **backup/restore** (`restore-backup`), **server operations** (`server-stats`, `ssh-deploy`), and **sync/provisioning** (`invite-user`, `sync-client-dravox`, `screen-setup-guide`, `generate-devis`).
   - These functions are the main boundary where the app performs actions that should not happen directly in the browser.

8. **Player/runtime side**
   - The presence of `pages/Player.tsx`, `components/player/DiagnosticOverlay.tsx`, and `FallbackScreen.tsx` indicates a separate **screen/player runtime** path from the admin dashboard.
   - The player likely receives screen configuration, playlist/schedule assignments, and then renders content continuously with a fallback state when data is missing or offline.
   - `screen-utils` and screen-related hooks imply the player has device-specific behavior and status handling.

9. **Content rendering system**
   - The `components/widgets` folder defines a modular **widget renderer** for display content: clock, currency, fixed text, marquee, QR code, RSS, slideshow, and weather.
   - `WidgetRenderer` is the composition point, turning content records into displayable modules.
   - This suggests the platform supports **mixed-content playlists** rather than only static media.

10. **Creation and automation features**
   - `components/autoflow`, `pages/AutoFlow.tsx`, and `components/ai/SuggestTab.tsx` indicate a content creation flow that combines **manual editing** and **AI-assisted suggestions**.
   - `pages/AIAssistant.tsx` and the `ai-assistant` edge function show that AI is not just UI-only; it has a backend execution path.
   - These features likely generate or transform content that then enters the same playlist/schedule pipeline as manually created assets.

11. **Admin and governance area**
   - The `pages/Admin*` screens cover **users, licenses, requests, stats, server status, email, backup, and customization**.
   - This is a distinct operational subsystem from the day-to-day dashboard and likely requires elevated permissions.
   - `AdminBackup`, `AdminServerStatus`, and `AdminUsers` suggest the product is used in a managed deployment environment, not just self-serve content editing.

12. **UI and theming**
   - `components/ui` contains the shared design-system primitives from shadcn/ui, while `ThemeContext` and branding tabs show **theme/branding customization**.
   - The app also has presentation-oriented components like animated backgrounds, cursor glow, login particles, and notification UI.
   - This layer is purely presentational and sits on top of the domain/data hooks.

13. **Testing and tooling**
   - `vitest.config.ts` and `src/test` indicate **unit/integration tests** are part of the repo, with at least some behavior around screen ordering.
   - The project is built for local development with standard Vite tooling, TypeScript checks, and ESLint/PostCSS/Tailwind configuration.
   - `public/robots.txt` and `index.html` confirm a normal SPA deployment surface.

14. **How to diagram it**
   - The main diagram should show: **browser SPA** → **Supabase Auth/DB/Realtime/Storage** → **Supabase Edge Functions** for privileged workflows.
   - Inside the SPA, separate the **admin/dashboard shell**, the **player runtime**, and the **content/widget rendering layer**.
   - Put **establishment scoping** as a cross-cutting boundary around most data flows, since it governs what data every view and hook can access.

Main entry points: [`src/hooks/useScreens.ts`](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/hooks/useScreens.ts) (Data Hooks), [`src/pages/Dashboard.tsx`](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Dashboard.tsx) (Dashboard Pages), [`src/App.tsx`](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/App.tsx) (App Shell), [`supabase/functions/ai-assistant/index.ts`](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/supabase/functions/ai-assistant/index.ts) (Edge Functions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser SPA"]
  node_main(("Entry<br/>spa bootstrap<br/>[main.tsx]"))
  node_app["App Shell<br/>routing shell<br/>[App.tsx]"]
  node_layout["Dashboard Shell<br/>navigation layout"]
  node_dashboard["Dashboard Pages<br/>ops screens<br/>[Dashboard.tsx]"]
  node_player["Player Runtime<br/>screen runtime<br/>[Player.tsx]"]
  node_widgets["Widget System<br/>content renderer<br/>[WidgetRenderer.tsx]"]
  node_autoflow["AutoFlow<br/>content authoring<br/>[AutoFlow.tsx]"]
  node_auth["Auth Flows<br/>session/auth<br/>[Login.tsx]"]
  node_branding["Branding & Theme<br/>presentation<br/>[ThemeContext.tsx]"]
  node_screens["Screen Ops<br/>device management<br/>[ScreenManager.tsx]"]
  node_content["Content Ops<br/>media scheduling<br/>[Playlists.tsx]"]
  node_admin["Admin Console<br/>governance area<br/>[AdminUsers.tsx]"]
  node_support["Support Tools<br/>auxiliary workflows<br/>[useInboxEmails.ts]"]
end

subgraph group_backend["Supabase Backend"]
  node_supabaseclient["Supabase Client<br/>backend client<br/>[client.ts]"]
  node_migrations[("Schema Migrations<br/>postgres schema")]
  node_edgefunctions["Edge Functions<br/>server workflows<br/>[index.ts]"]
end

subgraph group_shared["Shared Domain"]
  node_establishments["Establishment Scope<br/>tenant boundary"]
  node_hooks["Data Hooks<br/>client data layer<br/>[useScreens.ts]"]
end

node_main -->|"mounts"| node_app
node_app -->|"uses"| node_layout
node_app -->|"routes"| node_auth
node_app -->|"routes"| node_player
node_layout -->|"scopes"| node_establishments
node_dashboard -->|"reads"| node_hooks
node_content -->|"reads"| node_hooks
node_screens -->|"reads"| node_hooks
node_player -->|"renders"| node_widgets
node_autoflow -->|"produces"| node_widgets
node_hooks -->|"queries"| node_supabaseclient
node_supabaseclient -.->|"targets"| node_migrations
node_supabaseclient -->|"invokes"| node_edgefunctions
node_edgefunctions -->|"mutates"| node_migrations
node_establishments -.->|"constrains"| node_hooks
node_branding -->|"skins"| node_layout
node_admin -->|"administers"| node_edgefunctions
node_support -->|"triggers"| node_edgefunctions
node_support -->|"reads"| node_hooks
node_dashboard -->|"contains"| node_screens
node_dashboard -->|"contains"| node_content
node_dashboard -->|"contains"| node_admin

click node_main "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/main.tsx"
click node_app "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/App.tsx"
click node_layout "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/DashboardLayout.tsx"
click node_establishments "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/contexts/EstablishmentContext.tsx"
click node_dashboard "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Dashboard.tsx"
click node_player "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Player.tsx"
click node_widgets "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/widgets/WidgetRenderer.tsx"
click node_autoflow "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/AutoFlow.tsx"
click node_hooks "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/hooks/useScreens.ts"
click node_supabaseclient "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/integrations/supabase/client.ts"
click node_migrations "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/supabase/migrations/20260306183319_5aaa953e-411e-4822-ba83-113c480c5844.sql"
click node_edgefunctions "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/supabase/functions/ai-assistant/index.ts"
click node_auth "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Login.tsx"
click node_branding "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/contexts/ThemeContext.tsx"
click node_screens "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/dashboard/ScreenManager.tsx"
click node_content "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Playlists.tsx"
click node_admin "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/AdminUsers.tsx"
click node_support "https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/hooks/useInboxEmails.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_main,node_app,node_layout,node_dashboard,node_player,node_widgets,node_autoflow,node_auth,node_branding,node_screens,node_content,node_admin,node_support toneBlue
class node_supabaseclient,node_migrations,node_edgefunctions toneAmber
class node_establishments,node_hooks toneMint
```

## Components

### Browser SPA

React/Vite client-side application, UI, routing, and player runtime.

- [Entry](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/main.tsx): spa bootstrap · Vite entrypoint that mounts the React application. · `src/main.tsx`
- [App Shell](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/App.tsx): routing shell · Top-level routing and app composition for authenticated and public flows. · `src/App.tsx`
- [Dashboard Shell](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/DashboardLayout.tsx): navigation layout · Persistent authenticated layout with sidebar and navigation chrome. · `src/components/DashboardLayout.tsx`
- [Dashboard Pages](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Dashboard.tsx): ops screens · Operational screens for overview, displays, playlists, schedules, library, layouts, team, resources, and admin views. · `src/pages/Dashboard.tsx`
- [Player Runtime](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Player.tsx): screen runtime · Dedicated playback path for screens, diagnostics, and fallback rendering. · `src/pages/Player.tsx`
- [Widget System](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/widgets/WidgetRenderer.tsx): content renderer · Composable widgets and renderer used to display dynamic signage content. · `src/components/widgets/WidgetRenderer.tsx`
- [AutoFlow](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/AutoFlow.tsx): content authoring · Manual and AI-assisted content creation flow for generating display-ready content. · `src/pages/AutoFlow.tsx`
- [Auth Flows](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Login.tsx): session/auth · Login, registration, password reset, and auto-logout behavior. · `src/pages/Login.tsx`
- [Branding & Theme](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/contexts/ThemeContext.tsx): presentation · Theme, branding, and visual presentation customization. · `src/contexts/ThemeContext.tsx`
- [Screen Ops](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/components/dashboard/ScreenManager.tsx): device management · Management of screens, realtime status, licensing, setup, and video walls. · `src/components/dashboard/ScreenManager.tsx`
- [Content Ops](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/Playlists.tsx): media scheduling · Playlists, schedules, layouts, media library, playlists items, and programs management. · `src/pages/Playlists.tsx`
- [Admin Console](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/pages/AdminUsers.tsx): governance area · High-privilege operations for users, licenses, requests, stats, email, backup, server status, and customization. · `src/pages/AdminUsers.tsx`
- [Support Tools](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/hooks/useInboxEmails.ts): auxiliary workflows · Inbox email monitoring, notifications, assign/license flows, and onboarding helpers. · `src/hooks/useInboxEmails.ts`

### Supabase Backend

Auth, database, realtime, storage, migrations, and edge functions.

- [Supabase Client](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/integrations/supabase/client.ts): backend client · Client initialization and generated database types for Supabase access. · `src/integrations/supabase/client.ts`
- [Schema Migrations](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/supabase/migrations/20260306183319_5aaa953e-411e-4822-ba83-113c480c5844.sql): postgres schema · Source of truth for tables, relationships, and database rules. · `supabase/migrations/20260306183319_5aaa953e-411e-4822-ba83-113c480c5844.sql`
- [Edge Functions](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/supabase/functions/ai-assistant/index.ts): server workflows · Privileged workflows for admin bootstrap, email processing, content actions, backup, sync, and AI. · `supabase/functions/ai-assistant/index.ts`

### Shared Domain

Cross-cutting app logic shared across the client experience.

- [Establishment Scope](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/contexts/EstablishmentContext.tsx): tenant boundary · Context and switcher for scoping data and UI by establishment. · `src/contexts/EstablishmentContext.tsx`
- [Data Hooks](https://github.com/zeidzahouani-lgtm/radiantdisplay-hub/blob/main/src/hooks/useScreens.ts): client data layer · Domain hooks that wrap Supabase access, realtime updates, and establishment-aware queries. · `src/hooks/useScreens.ts`

## Connections

- Entry → App Shell: mounts · Bootstraps the routed application.
- App Shell → Dashboard Shell: uses · Authenticated routes render inside the dashboard shell.
- App Shell → Auth Flows: routes · Public auth and account recovery screens.
- App Shell → Player Runtime: routes · Dedicated screen playback route.
- Dashboard Shell → Establishment Scope: scopes · Navigation and views are filtered by the active establishment.
- Dashboard Pages → Data Hooks: reads · Operational screens consume domain hooks for data.
- Content Ops → Data Hooks: reads · Content management is backed by query hooks.
- Screen Ops → Data Hooks: reads · Device and wall management use realtime-aware hooks.
- Player Runtime → Widget System: renders · Playback path turns content into visual widgets.
- AutoFlow → Widget System: produces · AI/manual content flows feed the same renderer pipeline.
- Data Hooks → Supabase Client: queries · Hooks call into the Supabase client and generated types.
- Supabase Client → Schema Migrations: targets · Client data model matches the migrated schema.
- Supabase Client → Edge Functions: invokes · Client can call privileged server workflows when needed.
- Edge Functions → Schema Migrations: mutates · Functions operate on the same Postgres-backed domain data.
- Establishment Scope → Data Hooks: constrains · Tenant scope influences nearly all domain queries.
- Branding & Theme → Dashboard Shell: skins · Theme and branding customize the shared shell.
- Admin Console → Edge Functions: administers · Sensitive operational tasks are delegated to server-side functions.
- Support Tools → Edge Functions: triggers · Onboarding, inbox, and notification workflows reach backend actions.
- Support Tools → Data Hooks: reads · Support features also consume domain data hooks.
- Dashboard Pages → Screen Ops: contains · The dashboard surface includes screen management flows.
- Dashboard Pages → Content Ops: contains · The dashboard surface includes content and scheduling flows.
- Dashboard Pages → Admin Console: contains · Administrative screens live alongside operational areas.
