niamhramadhaan/jemima

1. JEMIMA is a single-repo, locally hosted digital-signage app with three runtime pieces: a React/Vite TypeScript front end, a small Node/Express server for serving media files, and an optional Electron shell for kiosk/desktop deployment.

2. The main architecture boundary is between UI state and media assets. Business data such as screens, schedules, preferences, and theme selection live in browser localStorage via shared hooks/utilities, while actual media files live on disk in a project-root media folder and are streamed by the server.

3. The front end is route-based. App.tsx wires navigation and access flow, while main.tsx boots the app. Pages under src/pages represent the major product surfaces: dashboard, films/library, ingest, schedules, show builder, locations/screens, player views, settings, login, and onboarding/quick start.

4. The admin/control plane is centered on the Dashboard, Schedule, Films, Locations, and Settings pages. These screens let a user import files, assemble playback sequences, assign schedules to screens, inspect status, and change app-wide options without any backend API or database.

5. Playback is split into dedicated player surfaces: Player, ScreenPlayer, PlayerConfig, and related screen detail pages. This separation reflects the product model where the same app can act as both operator console and display player, with fullscreen/kiosk behavior emphasized for installed screens.

6. Scheduling is the core domain model. The ShowBuilder and Schedule pages create ordered sequences of media items, support time-based start behavior, loop vs one-shot modes, background audio, and conflict detection. The dashboard then consumes that schedule state to show now-playing, next-up, and completion status.

7. Media ingestion is filesystem-first rather than upload-based. FilmIngest reads local files from the content directory, supported media types are indexed into the library, and player views load those assets from the Node server rather than from a cloud store.

8. Shared UI is organized as a reusable shell plus feature components. Layout, Sidebar, Topbar, Pagination, LocationTimeline, LocationsMap, SetlistModal, and ErrorBoundary provide the app frame and operational widgets, while src/components/ui contains decorative theme-driven primitives like the highlighter and light rays.

9. Theme and configuration are treated as first-class app state. themes.ts, src/lib/theme.ts, and src/config/app.ts define the accent system and app constants, and the useLocalStorage hook plus storage.ts/data.ts helpers centralize persistence and retrieval of user preferences and domain records.

10. The Electron layer is a packaging boundary, not a separate product tier. electron/main.cjs and electron/preload.cjs wrap the same app for standalone kiosk use, embedding the Express server so a dedicated display machine can launch JEMIMA without running a separate browser and server setup.

11. Architecturally, there are no external cloud services, no database, and no real auth system. That keeps the system simple and local-first, but also means the repository’s state is intentionally per-device and best understood as a single-node signage controller with browser-based multi-screen views.