Technical Overview: Hypenosys Dashboard

Technical Overview: Hypenosys Dashboard

Architecture: “Serverless” Jekyll & GitHub API

The Hypenosys Dashboard is a static site generated by Jekyll, hosted on GitHub Pages, and powered by a “serverless” architecture where all business logic and state management happen on the client side (browser).

1. Data Persistence

Data is persisted in the repository itself within the _data/ directory as JSON files. This creates a “git-as-a-database” model.

  • dashboard_tasks.json: Current Kanban board tasks.
  • team_profiles.json: Team member configurations and AI preferences.
  • studio_stats.json: Computed performance metrics.

2. GitHub API Integration (assets/javascript/github-api.js)

All write operations are performed through the GitHub Contents API.

  • Atomic Writes: To prevent data loss from concurrent edits (409 Conflict), we use a custom atomicWrite engine that fetches the latest SHA, applies changes, and retries with merging if necessary.
  • OAuth Authentication: Managed via a Cloudflare Worker Gatekeeper that exchanges temporary codes for access tokens, stored securely in sessionStorage/localStorage.

3. Modular JavaScript

The dashboard logic is split into functional modules to ensure maintainability:

  • github-api.js: Core communication with GitHub.
  • dashboard-ui.js: Orchestrates UI rendering with Error Boundary protection.
  • dashboard-tasks.js: Business logic for task lifecycle (create, edit, archive).
  • neural-chat-*.js: Integration with Claude and Jules AI agents.

4. Component Safety

We use a vanilla JS Error Boundary system (assets/javascript/error-boundary.js). If one component (like a specific chart) fails, it doesn’t crash the entire dashboard; instead, it renders a fallback UI.

Data Flow for a Feature

  1. User Action: User clicks “Save” on a task.
  2. Validation: task-engine.js validates the data.
  3. Write: github-api.js performs an atomicWrite to _data/dashboard_tasks.json.
  4. Trigger: Upon success, recomputeAndSaveStats is called to update metrics.
  5. Sync: Other open tabs are notified via localStorage events to refresh their view.

Development Principles

  • No NPM in Production: Use vanilla JS and declared libraries (Bootstrap 4, jQuery, Tailwind CDN).
  • English Code, Spanish Docs: Identifiers should be in English; JSDoc and comments in Spanish for local onboarding.
  • Defensive Rendering: Always use .textContent for user-generated data to prevent XSS.