# project-name-here/opencountdown architecture

> Architecture diagram of the GitHub repository project-name-here/opencountdown, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/project-name-here/opencountdown
- Repository: https://github.com/project-name-here/opencountdown

## Overview

openCountdown is a locally hosted event-countdown application, optionally wrapped in an Electron desktop shell. Operators configure timer state through the admin panel; the server exposes controls and distributes state to timer displays, which render countdown modes, progress and messages. The graph also shows the desktop lifecycle and a small server utility layer. Several server routes and the state-broadcast implementation were not included in the excerpts, so uncertain internal wiring is omitted.

Main entry points: [`index.js`](https://github.com/project-name-here/opencountdown/blob/master/index.js) (HTTP server and routes), [`startHandler.js`](https://github.com/project-name-here/opencountdown/blob/master/startHandler.js) (Desktop lifecycle), [`electronAssets/window.js`](https://github.com/project-name-here/opencountdown/blob/master/electronAssets/window.js) (Status window), [`templates/ng-timerview.html`](https://github.com/project-name-here/opencountdown/blob/master/templates/ng-timerview.html) (Timer page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_electron["Desktop lifecycle<br/>[startHandler.js]"]
  node_desktop_window["Status window<br/>[window.js]"]
  node_preload["IPC bridge<br/>[windowPreload.js]"]
end

subgraph group_server["Countdown server"]
  node_server["HTTP server and routes<br/>[index.js]"]
  node_state["Live countdown state<br/>[index.js]"]
  node_websocket["WebSocket updates<br/>[index.js]"]
  node_templates["Page templates"]
  node_language["Language profiles"]
end

subgraph group_admin["Admin controls"]
  node_admin_ui["Admin panel<br/>[newAdminPanel.html]"]
  node_admin_logic["Admin interactions<br/>[interface.js]"]
end

subgraph group_display["Timer displays"]
  node_timer_page["Timer page<br/>[ng-timerview.html]"]
  node_timer_logic["Timer rendering<br/>[timerview.js]"]
  node_legacy_page["Legacy timer page<br/>[timerPage.html]"]
  node_legacy_logic["Legacy timer rendering<br/>[script.js]"]
end

subgraph group_internal["Server utilities"]
  node_helpers["Input helpers<br/>[helpers.js]"]
  node_logging["Logging<br/>[logging.js]"]
end

node_operator(("Operator"))
node_audience(("Event audience"))

node_electron -->|"starts process"| node_server
node_electron -->|"polls status"| node_server
node_desktop_window -->|"sends IPC"| node_preload
node_preload -->|"forwards IPC"| node_electron
node_electron -->|"sends status"| node_desktop_window
node_operator -->|"uses controls"| node_desktop_window
node_operator -->|"configures timer"| node_admin_ui
node_server -->|"renders pages"| node_templates
node_server -->|"loads translations"| node_language
node_admin_ui -->|"loads interactions"| node_admin_logic
node_admin_logic -->|"sends API requests"| node_server
node_server -->|"updates state"| node_state
node_server -->|"converts inputs"| node_helpers
node_server -->|"logs events"| node_logging
node_server -->|"sets up updates"| node_websocket
node_websocket -->|"distributes state"| node_state
node_server -->|"serves page"| node_timer_page
node_server -->|"serves page"| node_legacy_page
node_timer_page -->|"loads renderer"| node_timer_logic
node_legacy_page -->|"loads renderer"| node_legacy_logic
node_timer_logic -->|"receives state"| node_websocket
node_legacy_logic -->|"receives state"| node_websocket
node_audience -->|"views countdown"| node_timer_page
node_audience -->|"views countdown"| node_legacy_page

click node_electron "https://github.com/project-name-here/opencountdown/blob/master/startHandler.js"
click node_desktop_window "https://github.com/project-name-here/opencountdown/blob/master/electronAssets/window.js"
click node_preload "https://github.com/project-name-here/opencountdown/blob/master/electronAssets/windowPreload.js"
click node_server "https://github.com/project-name-here/opencountdown/blob/master/index.js"
click node_state "https://github.com/project-name-here/opencountdown/blob/master/index.js"
click node_websocket "https://github.com/project-name-here/opencountdown/blob/master/index.js"
click node_templates "https://github.com/project-name-here/opencountdown/tree/master/templates"
click node_language "https://github.com/project-name-here/opencountdown/tree/master/lang"
click node_admin_ui "https://github.com/project-name-here/opencountdown/blob/master/templates/newAdminPanel.html"
click node_admin_logic "https://github.com/project-name-here/opencountdown/blob/master/static/js/interface.js"
click node_timer_page "https://github.com/project-name-here/opencountdown/blob/master/templates/ng-timerview.html"
click node_timer_logic "https://github.com/project-name-here/opencountdown/blob/master/static/js/timer/timerview.js"
click node_legacy_page "https://github.com/project-name-here/opencountdown/blob/master/templates/timerPage.html"
click node_legacy_logic "https://github.com/project-name-here/opencountdown/blob/master/static/js/script.js"
click node_helpers "https://github.com/project-name-here/opencountdown/blob/master/helpers.js"
click node_logging "https://github.com/project-name-here/opencountdown/blob/master/logging.js"

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_electron,node_desktop_window,node_preload toneBlue
class node_server,node_state,node_websocket,node_templates,node_language toneAmber
class node_admin_ui,node_admin_logic toneMint
class node_timer_page,node_timer_logic,node_legacy_page,node_legacy_logic toneRose
class node_helpers,node_logging,node_operator,node_audience toneIndigo
```

## Components

### Desktop shell

- [Desktop lifecycle](https://github.com/project-name-here/opencountdown/blob/master/startHandler.js): `startHandler.js`
- [Status window](https://github.com/project-name-here/opencountdown/blob/master/electronAssets/window.js): `electronAssets/window.js`
- [IPC bridge](https://github.com/project-name-here/opencountdown/blob/master/electronAssets/windowPreload.js): `electronAssets/windowPreload.js`

### Countdown server

- [HTTP server and routes](https://github.com/project-name-here/opencountdown/blob/master/index.js): `index.js`
- [Live countdown state](https://github.com/project-name-here/opencountdown/blob/master/index.js): `index.js`
- [WebSocket updates](https://github.com/project-name-here/opencountdown/blob/master/index.js): `index.js`
- [Page templates](https://github.com/project-name-here/opencountdown/tree/master/templates): `templates`
- [Language profiles](https://github.com/project-name-here/opencountdown/tree/master/lang): `lang`

### Admin controls

- [Admin panel](https://github.com/project-name-here/opencountdown/blob/master/templates/newAdminPanel.html): `templates/newAdminPanel.html`
- [Admin interactions](https://github.com/project-name-here/opencountdown/blob/master/static/js/interface.js): `static/js/interface.js`

### Timer displays

- [Timer page](https://github.com/project-name-here/opencountdown/blob/master/templates/ng-timerview.html): `templates/ng-timerview.html`
- [Timer rendering](https://github.com/project-name-here/opencountdown/blob/master/static/js/timer/timerview.js): `static/js/timer/timerview.js`
- [Legacy timer page](https://github.com/project-name-here/opencountdown/blob/master/templates/timerPage.html): `templates/timerPage.html`
- [Legacy timer rendering](https://github.com/project-name-here/opencountdown/blob/master/static/js/script.js): `static/js/script.js`

### Server utilities

- [Input helpers](https://github.com/project-name-here/opencountdown/blob/master/helpers.js): `helpers.js`
- [Logging](https://github.com/project-name-here/opencountdown/blob/master/logging.js): `logging.js`

### Other components

- **Operator**
- **Event audience**

## Connections

- Desktop lifecycle → HTTP server and routes: starts process
- Desktop lifecycle → HTTP server and routes: polls status
- Status window → IPC bridge: sends IPC
- IPC bridge → Desktop lifecycle: forwards IPC
- Desktop lifecycle → Status window: sends status
- Operator → Status window: uses controls
- Operator → Admin panel: configures timer
- HTTP server and routes → Page templates: renders pages
- HTTP server and routes → Language profiles: loads translations
- Admin panel → Admin interactions: loads interactions
- Admin interactions → HTTP server and routes: sends API requests
- HTTP server and routes → Live countdown state: updates state
- HTTP server and routes → Input helpers: converts inputs
- HTTP server and routes → Logging: logs events
- HTTP server and routes → WebSocket updates: sets up updates
- WebSocket updates → Live countdown state: distributes state
- HTTP server and routes → Timer page: serves page
- HTTP server and routes → Legacy timer page: serves page
- Timer page → Timer rendering: loads renderer
- Legacy timer page → Legacy timer rendering: loads renderer
- Timer rendering → WebSocket updates: receives state
- Legacy timer rendering → WebSocket updates: receives state
- Event audience → Timer page: views countdown
- Event audience → Legacy timer page: views countdown