# ath31st/feedjet architecture

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

- Interactive diagram: https://gitdiagram.com/ath31st/feedjet
- Repository: https://github.com/ath31st/feedjet

## Overview

Feedjet is a digital-signage system: administrators configure kiosks, scenarios, media and schedules; kiosk clients then play those scenarios and refresh configuration over SSE. The client is organized as routes/pages, widgets and features backed by entity API hooks. The server exposes tRPC services, persistent domain data, media processing and device integrations. Several server subsystems are documented but their route-level wiring is not sampled, so those links are shown only where the README or excerpts establish them.

Main entry points: [`server/src/container.ts`](https://github.com/ath31st/feedjet/blob/master/server/src/container.ts) (Service composition), [`client/src/pages/admin/ui/AdminPage.tsx`](https://github.com/ath31st/feedjet/blob/master/client/src/pages/admin/ui/AdminPage.tsx) (Admin page), [`client/src/app/routes/router.tsx`](https://github.com/ath31st/feedjet/blob/master/client/src/app/routes/router.tsx) (Route selection), [`server/src/services/image.storage.service.ts`](https://github.com/ath31st/feedjet/blob/master/server/src/services/image.storage.service.ts) (Image processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_runtime["Kiosk runtime"]
  node_router["Route selection<br/>[router.tsx]"]
  node_kiosk_page["Kiosk page<br/>[KioskPage.tsx]"]
  node_kiosk_init["Kiosk initialization"]
  node_scenario_rotation["Scenario rotation"]
  node_scenario_renderer["Scenario rendering"]
  node_widgets["Screen widgets"]
  node_sse_client["SSE updates<br/>[useSseStream.ts]"]
end

subgraph group_client_admin["Administration"]
  node_admin_page["Admin page<br/>[AdminPage.tsx]"]
  node_scenario_editor["Scenario editing<br/>[ScenarioEditor.tsx]"]
  node_media_management["Media library"]
  node_admin_widgets["Admin capabilities"]
end

subgraph group_server_domain["Server domain"]
  node_scenario_service["Scenario service"]
  node_media_routes["Media upload routes"]
  node_image_service["Image processing"]
  node_video_service["Video processing"]
  node_pdf_service["PDF processing"]
  node_file_storage["File storage"]
  node_device_services["Device control"]
end

subgraph group_server_platform["Server platform"]
  node_trpc_client["tRPC client<br/>[trpc.ts]"]
  node_api_routes["tRPC API<br/>[index.ts]"]
  node_auth["Protected procedures<br/>[auth.ts]"]
  node_container["Service composition<br/>[container.ts]"]
  node_database[("SQLite data<br/>[schema.ts]")]
  node_philips["Philips JointSpace"]
  node_sse_server["SSE handler"]
end

node_admin(("Administrator"))
node_kiosk_screen(("Kiosk screen"))
node_device(("Managed display"))

node_admin -->|"opens admin"| node_router
node_kiosk_screen -->|"opens playback"| node_router
node_router -->|"routes to"| node_admin_page
node_router -->|"routes to"| node_kiosk_page
node_kiosk_page -.->|"initializes"| node_kiosk_init
node_kiosk_init -.->|"loads playback"| node_scenario_rotation
node_scenario_rotation -.->|"selects items"| node_scenario_renderer
node_scenario_renderer -->|"renders widgets"| node_widgets
node_kiosk_init -->|"starts updates"| node_sse_client
node_admin_page -.->|"offers editing"| node_scenario_editor
node_admin_page -.->|"offers library"| node_media_management
node_admin_page -.->|"presents tools"| node_admin_widgets
node_scenario_editor -.->|"saves scenarios"| node_trpc_client
node_media_management -.->|"uploads media"| node_trpc_client
node_trpc_client -->|"calls tRPC"| node_api_routes
node_api_routes -->|"guards requests"| node_auth
node_api_routes -->|"uses services"| node_container
node_container -->|"constructs"| node_scenario_service
node_container -->|"constructs"| node_image_service
node_container -->|"constructs"| node_video_service
node_container -->|"constructs"| node_pdf_service
node_media_routes -->|"uploads through"| node_image_service
node_image_service -->|"inherits storage"| node_file_storage
node_video_service -->|"uses storage"| node_file_storage
node_pdf_service -->|"uses storage"| node_file_storage
node_image_service -->|"stores metadata"| node_database
node_video_service -->|"stores metadata"| node_database
node_pdf_service -->|"stores metadata"| node_database
node_container -->|"constructs"| node_device_services
node_device_services -->|"controls display"| node_philips
node_device_services -.->|"manages"| node_device
node_sse_client -.->|"receives updates"| node_sse_server
node_sse_server -.->|"streams config"| node_kiosk_screen

click node_router "https://github.com/ath31st/feedjet/blob/master/client/src/app/routes/router.tsx"
click node_kiosk_page "https://github.com/ath31st/feedjet/blob/master/client/src/pages/KioskPage.tsx"
click node_kiosk_init "https://github.com/ath31st/feedjet/blob/master/client/src/app/init/KioskInitializer.tsx"
click node_scenario_rotation "https://github.com/ath31st/feedjet/blob/master/client/src/features/kiosk-rotation/model/useScenarioRotation.ts"
click node_scenario_renderer "https://github.com/ath31st/feedjet/blob/master/client/src/features/scenario-renderer/ui/ScenarioItemRenderer.tsx"
click node_widgets "https://github.com/ath31st/feedjet/tree/master/client/src/widgets"
click node_sse_client "https://github.com/ath31st/feedjet/blob/master/client/src/app/init/useSseStream.ts"
click node_admin_page "https://github.com/ath31st/feedjet/blob/master/client/src/pages/admin/ui/AdminPage.tsx"
click node_scenario_editor "https://github.com/ath31st/feedjet/blob/master/client/src/features/scenario-editor/ui/ScenarioEditor.tsx"
click node_media_management "https://github.com/ath31st/feedjet/blob/master/client/src/widgets/media-management/model/useMediaManagementWidget.ts"
click node_admin_widgets "https://github.com/ath31st/feedjet/tree/master/client/src/widgets"
click node_trpc_client "https://github.com/ath31st/feedjet/blob/master/client/src/shared/api/trpc/trpc.ts"
click node_api_routes "https://github.com/ath31st/feedjet/blob/master/server/src/trpc/index.ts"
click node_auth "https://github.com/ath31st/feedjet/blob/master/server/src/middleware/auth.ts"
click node_container "https://github.com/ath31st/feedjet/blob/master/server/src/container.ts"
click node_scenario_service "https://github.com/ath31st/feedjet/blob/master/server/src/services/scenario.service.ts"
click node_media_routes "https://github.com/ath31st/feedjet/blob/master/server/src/trpc/routes/image.storage.route.ts"
click node_image_service "https://github.com/ath31st/feedjet/blob/master/server/src/services/image.storage.service.ts"
click node_video_service "https://github.com/ath31st/feedjet/blob/master/server/src/services/video.storage.service.ts"
click node_pdf_service "https://github.com/ath31st/feedjet/blob/master/server/src/services/pdf.storage.service.ts"
click node_file_storage "https://github.com/ath31st/feedjet/blob/master/server/src/services/file.storage.service.ts"
click node_database "https://github.com/ath31st/feedjet/blob/master/server/src/db/schema.ts"
click node_device_services "https://github.com/ath31st/feedjet/blob/master/server/src/services/integration.service.ts"
click node_philips "https://github.com/ath31st/feedjet/blob/master/server/src/integration/philips.jointspace.client.ts"
click node_sse_server "https://github.com/ath31st/feedjet/blob/master/server/src/sse/unified.sse.handler.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_router,node_kiosk_page,node_kiosk_init,node_scenario_rotation,node_scenario_renderer,node_widgets,node_sse_client,node_kiosk_screen toneBlue
class node_admin_page,node_scenario_editor,node_media_management,node_admin_widgets toneAmber
class node_scenario_service,node_media_routes,node_image_service,node_video_service,node_pdf_service,node_file_storage,node_device_services toneMint
class node_trpc_client,node_api_routes,node_auth,node_container,node_database,node_philips,node_sse_server toneRose
class node_admin,node_device toneIndigo
```

## Components

### Kiosk runtime

- [Route selection](https://github.com/ath31st/feedjet/blob/master/client/src/app/routes/router.tsx): `client/src/app/routes/router.tsx`
- [Kiosk page](https://github.com/ath31st/feedjet/blob/master/client/src/pages/KioskPage.tsx): `client/src/pages/KioskPage.tsx`
- [Kiosk initialization](https://github.com/ath31st/feedjet/blob/master/client/src/app/init/KioskInitializer.tsx): `client/src/app/init/KioskInitializer.tsx`
- [Scenario rotation](https://github.com/ath31st/feedjet/blob/master/client/src/features/kiosk-rotation/model/useScenarioRotation.ts): `client/src/features/kiosk-rotation/model/useScenarioRotation.ts`
- [Scenario rendering](https://github.com/ath31st/feedjet/blob/master/client/src/features/scenario-renderer/ui/ScenarioItemRenderer.tsx): `client/src/features/scenario-renderer/ui/ScenarioItemRenderer.tsx`
- [Screen widgets](https://github.com/ath31st/feedjet/tree/master/client/src/widgets): `client/src/widgets`
- [SSE updates](https://github.com/ath31st/feedjet/blob/master/client/src/app/init/useSseStream.ts): `client/src/app/init/useSseStream.ts`

### Administration

- [Admin page](https://github.com/ath31st/feedjet/blob/master/client/src/pages/admin/ui/AdminPage.tsx): `client/src/pages/admin/ui/AdminPage.tsx`
- [Scenario editing](https://github.com/ath31st/feedjet/blob/master/client/src/features/scenario-editor/ui/ScenarioEditor.tsx): `client/src/features/scenario-editor/ui/ScenarioEditor.tsx`
- [Media library](https://github.com/ath31st/feedjet/blob/master/client/src/widgets/media-management/model/useMediaManagementWidget.ts): `client/src/widgets/media-management/model/useMediaManagementWidget.ts`
- [Admin capabilities](https://github.com/ath31st/feedjet/tree/master/client/src/widgets): `client/src/widgets`

### Server domain

- [Scenario service](https://github.com/ath31st/feedjet/blob/master/server/src/services/scenario.service.ts): `server/src/services/scenario.service.ts`
- [Media upload routes](https://github.com/ath31st/feedjet/blob/master/server/src/trpc/routes/image.storage.route.ts): `server/src/trpc/routes/image.storage.route.ts`
- [Image processing](https://github.com/ath31st/feedjet/blob/master/server/src/services/image.storage.service.ts): `server/src/services/image.storage.service.ts`
- [Video processing](https://github.com/ath31st/feedjet/blob/master/server/src/services/video.storage.service.ts): `server/src/services/video.storage.service.ts`
- [PDF processing](https://github.com/ath31st/feedjet/blob/master/server/src/services/pdf.storage.service.ts): `server/src/services/pdf.storage.service.ts`
- [File storage](https://github.com/ath31st/feedjet/blob/master/server/src/services/file.storage.service.ts): `server/src/services/file.storage.service.ts`
- [Device control](https://github.com/ath31st/feedjet/blob/master/server/src/services/integration.service.ts): `server/src/services/integration.service.ts`

### Server platform

- [tRPC client](https://github.com/ath31st/feedjet/blob/master/client/src/shared/api/trpc/trpc.ts): `client/src/shared/api/trpc/trpc.ts`
- [tRPC API](https://github.com/ath31st/feedjet/blob/master/server/src/trpc/index.ts): `server/src/trpc/index.ts`
- [Protected procedures](https://github.com/ath31st/feedjet/blob/master/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Service composition](https://github.com/ath31st/feedjet/blob/master/server/src/container.ts): `server/src/container.ts`
- [SQLite data](https://github.com/ath31st/feedjet/blob/master/server/src/db/schema.ts): `server/src/db/schema.ts`
- [Philips JointSpace](https://github.com/ath31st/feedjet/blob/master/server/src/integration/philips.jointspace.client.ts): `server/src/integration/philips.jointspace.client.ts`
- [SSE handler](https://github.com/ath31st/feedjet/blob/master/server/src/sse/unified.sse.handler.ts): `server/src/sse/unified.sse.handler.ts`

### Other components

- **Administrator**
- **Kiosk screen**
- **Managed display**

## Connections

- Administrator → Route selection: opens admin (evidence: `client/src/app/routes/router.tsx`)
- Kiosk screen → Route selection: opens playback (evidence: `client/src/app/routes/router.tsx`)
- Route selection → Admin page: routes to (evidence: `client/src/app/routes/router.tsx`)
- Route selection → Kiosk page: routes to (evidence: `client/src/app/routes/router.tsx`)
- Kiosk page → Kiosk initialization: initializes
- Kiosk initialization → Scenario rotation: loads playback
- Scenario rotation → Scenario rendering: selects items
- Scenario rendering → Screen widgets: renders widgets
- Kiosk initialization → SSE updates: starts updates
- Admin page → Scenario editing: offers editing
- Admin page → Media library: offers library
- Admin page → Admin capabilities: presents tools
- Scenario editing → tRPC client: saves scenarios
- Media library → tRPC client: uploads media
- tRPC client → tRPC API: calls tRPC
- tRPC API → Protected procedures: guards requests
- tRPC API → Service composition: uses services
- Service composition → Scenario service: constructs (evidence: `server/src/container.ts`)
- Service composition → Image processing: constructs (evidence: `server/src/container.ts`)
- Service composition → Video processing: constructs (evidence: `server/src/container.ts`)
- Service composition → PDF processing: constructs (evidence: `server/src/container.ts`)
- Media upload routes → Image processing: uploads through (evidence: `server/src/trpc/routes/image.storage.route.ts`)
- Image processing → File storage: inherits storage
- Video processing → File storage: uses storage (evidence: `server/src/services/video.storage.service.ts`)
- PDF processing → File storage: uses storage (evidence: `server/src/services/pdf.storage.service.ts`)
- Image processing → SQLite data: stores metadata (evidence: `server/src/services/image.storage.service.ts`)
- Video processing → SQLite data: stores metadata (evidence: `server/src/services/video.storage.service.ts`)
- PDF processing → SQLite data: stores metadata (evidence: `server/src/services/pdf.storage.service.ts`)
- Service composition → Device control: constructs (evidence: `server/src/container.ts`)
- Device control → Philips JointSpace: controls display (evidence: `server/src/container.ts`)
- Device control → Managed display: manages
- SSE updates → SSE handler: receives updates
- SSE handler → Kiosk screen: streams config
