Initial commit — 2026-07-15

2026-07-15 17:32:04 -04:00
commit 55609f6e91
5 changed files with 647 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Digital Signage CMS — Project Overview
+
+## Concept
+Multi-tenant digital signage platform. Customers upload content (images, video) via a web portal, create playlists, and Raspberry Pi players pull and display content in fullscreen kiosk mode.
+
+## Architecture
+
+```
+┌─────────────────────────────┐     ┌──────────────────────────────┐
+│   Customer Portal (Web)      │     │   Raspberry Pi Player        │
+│                               │     │                              │
+│  ┌───────────────────────┐  │     │  ┌────────────────────────┐  │
+│  │ Login (auth per       │  │     │  │ Registration script     │  │
+│  │ customer/tenant)      │  │     │  │ P: POST /api/register   │  │
+│  ├───────────────────────┤  │     │  │  → gets device token    │  │
+│  │ Dashboard             │  │     │  ├────────────────────────┤  │
+│  │  - My Screens         │  │     │  │ Polling script          │  │
+│  │  - Content Library    │  │     │  │ GET /api/playlist/:id   │  │
+│  │  - Playlists          │  │     │  │  → returns content URLs │  │
+│  │  - Upload             │  │     │  ├────────────────────────┤  │
+│  ├───────────────────────┤  │     │  │ Chromium kiosk          │  │
+│  │ Admin (ITPP)          │  │     │  │ --kiosk --no-sandbox    │  │
+│  │  - All tenants        │  │     │  └────────────────────────┘  │
+│  │  - Device management  │  │     └──────────────────────────────┘
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+              │
+              ▼
+     ┌─────────────────┐
+     │  API + Storage   │
+     │                  │
+     │  FastAPI backend │
+     │  SQLite/S3       │
+     │  per tenant      │
+     └─────────────────┘
+```
+
+## Multi-Tenant Architecture
+
+### Tenant Hierarchy
+```
+Signage CMS (Platform)
+├── Tenant: Joe's Diner
+│   ├── User: alice@joesdiner.com (admin)
+│   ├── Device: Main Lobby Pi
+│   │   ├── Serial: 10000000a1b2c3d4
+│   │   ├── Status: Online
+│   │   └── Playlist: Main Menu Loop
+│   ├── Device: Menu Board Pi
+│   │   ├── Serial: 10000000e5f6g7h8
+│   │   ├── Status: Online
+│   │   └── Playlist: Daily Specials
+│   ├── Device: Waiting Room Pi
+│   │   ├── Serial: 10000000i9j0k1l2
+│   │   ├── Status: Offline
+│   │   └── Playlist: Promo Rotation
+│   └── Content: 8 items (4 images, 4 videos)
+│
+├── Tenant: Main Street Gym
+│   ├── User: owner@mainstreetgym.com
+│   └── Device: Front Desk Pi
+│
+└── Tenant: Third Coast Dental
+    ├── User: frontdesk@thirdcoast.com
+    ├── Device: Waiting Room Pi
+    ├── Device: Exam Room Pi
+    └── Device: Hallway Pi
+```
+
+### Key Design Points
+- **One customer = one tenant = unlimited devices**
+- Each device registers independently with a unique code + serial
+- Devices belong to a tenant, not directly to a user
+- Multiple users can manage the same tenant (owner + staff accounts)
+- Content libraries are per-tenant (shared across all their devices)
+- Playlists can be assigned to one or multiple devices
+- A device can only play ONE playlist at a time
+
+### Pi Registration Flow
+```
+1. Customer gets Pi with a unique registration code (printed or emailed)
+2. Pi boots → runs registration script
+3. Script calls POST /api/register with code + Pi serial number
+4. Server registers device under that tenant
+5. Pi receives device_id + auth token
+6. Pi starts polling GET /api/playlist/:device_id every 60s
+7. CMS pushes updates → Pi picks up new playlist on next poll
+```
+
+### Registration Script (on Pi)
+```bash
+#!/bin/bash
+# register-pi.sh
+REG_CODE="$1"
+PI_SERIAL=$(cat /proc/cpuinfo | grep Serial | awk '{print $3}')
+API="https://signage.itpropartner.com/api"
+
+curl -X POST "$API/register" \
+  -H "Content-Type: application/json" \
+  -d "{\"code\":\"$REG_CODE\",\"serial\":\"$PI_SERIAL\"}"
+```
+
+## MVP Scope (Phase 1)
+| Feature | Status |
+|---------|--------|
+| Customer login | To build |
+| Content upload (images + video) | To build |
+| Simple playlist (ordered) | To build |
+| Pi kiosk player script | To build |
+| Multi-tenant (tenant isolation) | To build |
+| Cloudflare proxy | Future |
+| Scheduling | Future |
+| Shuffled/random play | Future |
+| 4K detection via EDID | To research |
+
+## Stack
+- **Backend:** FastAPI + SQLite (same pattern as ops portal)
+- **Frontend:** Dark theme, mobile-responsive (PWA-ready)
+- **Player:** Raspberry Pi 3/4/5, Chromium kiosk, auto-updating
+- **Storage:** Local filesystem → S3 in future
+- **Auth:** JWT per tenant, admin override
+
+## Status
+📝 **Project created — MVP design underway**