# nahinio/playcore architecture

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

- Interactive diagram: https://gitdiagram.com/nahinio/playcore
- Repository: https://github.com/nahinio/playcore

## Overview

1. **Overall shape**
   - PlayCORE is a **desktop Electron application** with a clear split between:
     - **Main process** in `electron/`
     - **Renderer/UI layer** in `src/`
   - It is an **offline-first local course player/library**, not a client-server app. Most data stays on the user’s machine.

2. **Process boundary**
   - `electron/main.js` is the privileged process that creates and manages the application window.
   - `electron/preload.js` is the bridge layer that exposes a controlled API to the renderer.
   - `src/main.js` runs in the renderer and drives the UI, course browsing, playback, and search.

3. **Renderer subsystem**
   - `src/index.html`, `src/styles.css`, and `src/main.js` form the application’s UI layer.
   - This layer is responsible for the user-facing experience described in the README: minimalist interface, library browsing, media viewing, and progress-aware playback.
   - The renderer likely owns most of the state for the current course list, selected item, search results, and playback position display.

4. **Application shell / windowing**
   - The Electron main process is the outer shell around the app.
   - Because the README mentions a **frameless UI**, the main process likely configures a custom window without standard OS chrome.
   - This makes the shell behavior important: window creation, lifecycle, and app-level controls are separated from the content UI.

5. **Security and API boundary**
   - `preload.js` is a key architectural boundary: it lets the renderer call into system capabilities without direct Node.js access.
   - This usually means file-system or media-related operations are exposed through a narrowed IPC/API surface rather than raw Electron access from the UI.

6. **Local content model**
   - The app is built around **user-provided local files** rather than remote content.
   - Supported content types from the README include **MP4, WebM, MP3, PDFs, and text files**.
   - The main data flow is from the user’s local filesystem into the library/UI, then into a viewer/player based on file type.

7. **Media and document handling**
   - The renderer likely routes different file types to different presentation modes:
     - video/audio playback for MP4/WebM/MP3
     - document/text viewing for PDF/text files
   - This implies a content-dispatch layer in the UI that selects the right viewer based on file metadata or extension.

8. **Progress tracking**
   - A core feature is **saving playback position for videos**.
   - The data flow is: user watches content → current position is captured → progress is persisted locally → later sessions restore that point.
   - This is an important architectural concern because it adds local persistence beyond simple playback.

9. **Search / library navigation**
   - The README calls out **fast search** and instant access to the course library.
   - Architecturally, this suggests the app maintains an indexed or in-memory representation of the local course catalog in the renderer, likely populated from filesystem scans or imported folders.

10. **Offline-first persistence**
    - There is no sign of a backend service, authentication system, or cloud sync.
    - Any persisted state such as progress, library metadata, or last-opened items is likely stored locally by the app.
    - This reinforces the boundary: filesystem and local app storage are the primary data sources/sinks.

11. **Assets and packaging**
    - `build/icon.png` and the `build/` directory indicate packaged desktop branding/artifacts.
    - The repository appears oriented toward distribution as an Electron app, where static assets and packaging metadata matter to the final executable.

12. **Technology stack**
    - Core runtime: **Electron**
    - UI: **plain HTML/CSS/JavaScript** in `src/`
    - No separate backend, database server, or network API is evident from the tree.
    - The architecture is therefore a single desktop executable with a renderer/main-process split.

13. **How to draw the diagram**
    - Show one outer box for the Electron desktop app.
    - Inside it, separate:
      - **Main process**: window lifecycle, app shell, privileged OS/file access
      - **Preload bridge**: safe IPC/API exposure
      - **Renderer/UI**: library browsing, search, media/document viewing, progress tracking
    - Draw arrows from the renderer to the preload bridge, then to the main process for privileged operations.
    - Draw arrows from the app to the **local filesystem** as the primary data source and persistence target.

14. **What is not present**
    - No evidence of a remote API, authentication, background job system, or multi-user backend.
    - The architecture is intentionally compact and local, with the main complexity concentrated in the renderer and the file/media handling path.

Main entry points: [`src/main.js`](https://github.com/nahinio/playcore/blob/main/src/main.js) (Renderer app), [`electron/preload.js`](https://github.com/nahinio/playcore/blob/main/electron/preload.js) (Preload bridge), [`electron/main.js`](https://github.com/nahinio/playcore/blob/main/electron/main.js) (Main process), [`package.json`](https://github.com/nahinio/playcore/blob/main/package.json) (Package manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_shell["Desktop shell"]
  node_n_app["PlayCORE<br/>Electron desktop app"]
  node_n_main["Main process<br/>privileged shell<br/>[main.js]"]
  node_n_preload["Preload bridge<br/>IPC bridge<br/>[preload.js]"]
  node_n_window["App window<br/>frameless window"]
end

subgraph group_group_ui["Renderer UI"]
  node_n_renderer["Renderer app<br/>UI runtime<br/>[main.js]"]
  node_n_markup["UI markup<br/>HTML shell<br/>[index.html]"]
  node_n_styles["Styling<br/>CSS theme<br/>[styles.css]"]
  node_n_library["Library view<br/>catalog UI"]
  node_n_search["Search<br/>filtering"]
  node_n_player["Media player<br/>playback UI"]
  node_n_viewer["Document viewer<br/>content viewer"]
end

subgraph group_group_data["Local content"]
  node_n_progress[("Progress state<br/>local state")]
  node_n_files[("Local files<br/>filesystem source")]
  node_n_catalog[("Course catalog<br/>local index")]
end

subgraph group_group_packaging["Packaging"]
  node_n_assets["Assets"]
  node_n_build["Build output<br/>packaging artifacts"]
  node_n_manifest["Package manifest<br/>npm metadata<br/>[package.json]"]
end

node_n_app -->|"starts"| node_n_main
node_n_main -->|"creates"| node_n_window
node_n_main -->|"loads"| node_n_preload
node_n_preload -->|"exposes API"| node_n_renderer
node_n_renderer -->|"renders"| node_n_markup
node_n_renderer -->|"applies"| node_n_styles
node_n_renderer -->|"coordinates"| node_n_library
node_n_renderer -->|"supports"| node_n_search
node_n_renderer -->|"routes media"| node_n_player
node_n_renderer -->|"routes docs"| node_n_viewer
node_n_renderer -->|"reads"| node_n_catalog
node_n_renderer -->|"updates"| node_n_progress
node_n_preload -->|"accesses"| node_n_files
node_n_preload -->|"persists"| node_n_progress
node_n_files -->|"builds"| node_n_catalog
node_n_catalog -->|"indexes"| node_n_search
node_n_assets -->|"supplies"| node_n_renderer
node_n_manifest -->|"configures"| node_n_main
node_n_manifest -->|"packages"| node_n_build

click node_n_main "https://github.com/nahinio/playcore/blob/main/electron/main.js"
click node_n_preload "https://github.com/nahinio/playcore/blob/main/electron/preload.js"
click node_n_renderer "https://github.com/nahinio/playcore/blob/main/src/main.js"
click node_n_markup "https://github.com/nahinio/playcore/blob/main/src/index.html"
click node_n_styles "https://github.com/nahinio/playcore/blob/main/src/styles.css"
click node_n_assets "https://github.com/nahinio/playcore/tree/main/src/assets"
click node_n_build "https://github.com/nahinio/playcore/tree/main/build"
click node_n_manifest "https://github.com/nahinio/playcore/blob/main/package.json"

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_n_app,node_n_main,node_n_preload,node_n_window toneBlue
class node_n_renderer,node_n_markup,node_n_styles,node_n_library,node_n_search,node_n_player,node_n_viewer toneAmber
class node_n_progress,node_n_files,node_n_catalog toneMint
class node_n_assets,node_n_build,node_n_manifest toneRose
```

## Components

### Desktop shell

Electron main-process boundary and app windowing

- **PlayCORE**: Electron desktop app · Offline-first local course player and library
- [Main process](https://github.com/nahinio/playcore/blob/main/electron/main.js): privileged shell · Creates the window and handles app-level lifecycle · `electron/main.js`
- [Preload bridge](https://github.com/nahinio/playcore/blob/main/electron/preload.js): IPC bridge · Exposes a narrowed API from Electron to the renderer · `electron/preload.js`
- **App window**: frameless window · Custom desktop window chrome and lifecycle

### Renderer UI

HTML/CSS/JS interface and playback logic

- [Renderer app](https://github.com/nahinio/playcore/blob/main/src/main.js): UI runtime · Drives browsing, search, playback, and state · `src/main.js`
- [UI markup](https://github.com/nahinio/playcore/blob/main/src/index.html): HTML shell · Application structure and view containers · `src/index.html`
- [Styling](https://github.com/nahinio/playcore/blob/main/src/styles.css): CSS theme · Minimal desktop presentation and layout · `src/styles.css`
- **Library view**: catalog UI · Course browsing and selection surface
- **Search**: filtering · Fast lookup across the local course catalog
- **Media player**: playback UI · Video and audio presentation for local media
- **Document viewer**: content viewer · PDF and text reading surface

### Local content

Filesystem-backed library, progress, and file handling

- **Progress state**: local state · Saved playback position and last-opened content
- **Local files**: filesystem source · User-provided MP4, WebM, MP3, PDF, and text files
- **Course catalog**: local index · In-memory or persisted representation of the library

### Packaging

Build-time desktop assets and distribution artifacts

- [Assets](https://github.com/nahinio/playcore/tree/main/src/assets): static assets · Icons and packaged UI resources · `src/assets`
- [Build output](https://github.com/nahinio/playcore/tree/main/build): packaging artifacts · Desktop packaging and release resources · `build`
- [Package manifest](https://github.com/nahinio/playcore/blob/main/package.json): npm metadata · App entry points and Electron packaging config · `package.json`

## Connections

- PlayCORE → Main process: starts · The app boots through the Electron main process
- Main process → App window: creates · Main process owns the desktop window
- Main process → Preload bridge: loads · Window setup wires in the preload bridge
- Preload bridge → Renderer app: exposes API · Safe access to privileged operations
- Renderer app → UI markup: renders · Renderer drives the visible UI structure
- Renderer app → Styling: applies · Styling shapes the minimalist interface
- Renderer app → Library view: coordinates · Library browsing is managed in the renderer
- Renderer app → Search: supports · Search filters the local catalog
- Renderer app → Media player: routes media · Media files are opened in playback mode
- Renderer app → Document viewer: routes docs · PDF and text content are opened in reader mode
- Renderer app → Course catalog: reads · UI state is driven by the local course index
- Renderer app → Progress state: updates · Playback position and session state are persisted locally
- Preload bridge → Local files: accesses · Controlled file-system operations flow through the bridge
- Preload bridge → Progress state: persists · Bridge stores and restores playback progress
- Local files → Course catalog: builds · Filesystem scans populate the course catalog
- Course catalog → Search: indexes · Search operates over the library representation
- Assets → Renderer app: supplies · Static assets support the UI
- Package manifest → Main process: configures · Manifest defines Electron entry points and packaging
- Package manifest → Build output: packages · Build resources feed desktop distribution
