OMNI-GRID // THE SUPER APP

generated_video.85.mp4

   ____  __  __ _   _ ___       ____ ____  ___ ____
  / __ \|  \/  | \ | |_ _|     / ___|  _ \|_ _|  _ \
 | |  | | |\/| |  \| || |_____| |  _| |_) || || | | |
 | |__| | |  | | |\  || |_____| |_| |  _ < | || |_| |
  \____/|_|  |_|_| \_|___|     \____|_| \_\___|____/

  [ SYSTEM STATUS: ONLINE ]
  [ PROTOCOL: LOCAL-FIRST ]

0x01 // OVERVIEW

Omni-Grid is a privacy-centric, local-first "Super App" designed to replace fragmented browser tabs with a unified, high-density command center. Built on a modular React grid architecture, it integrates "Smart Grid" financial intelligence, AI-powered drafting, and developer utilities into a single aesthetic interface.

Philosophy: "The net is vast and infinite, but your grid is your own."

📚 FULL DOCUMENTATION | 🗺️ ROADMAP | 🎯 PROJECT BLUEPRINT | 🚀 QUICK START | ❓ FAQ | 📊 PERFORMANCE REPORT | 🔄 CI/CD WORKFLOWS

0x01.1 // SCREENSHOTS

🖥️ Dashboard Overview

The main Omni-Grid dashboard with live widgets: System Core, Neural Scratchpad, Focus HUD, Market Widget, Valuta Exchange, Weather Station and more.

🚀 Widget Launcher

The Widget Launcher — search and activate any of the 40 available modules, organized by category (Neural, Finance, Dev, Creative, Research, System).

🛠️ Developer Tools

CyberEditor with AI-powered code generation, Prompt Lab for provider comparison, Neural Chat, and Git Pulse PR monitoring — all on one screen.

📊 Smart Grid & Creative Tools

Macro Net M2 correlation heatmap, Asset Command portfolio tracker, Reg Radar sentiment analysis, Sonic Architecture with Circle of Fifths, and Strategic Blueprint Kanban board.

---

0x02 // CORE MODULES

🧠 The Neural Suite

• Neural Scratchpad: AI-augmented note-taking (Refine, Expand, Summarize).
• WritePad: Auto-drafting for emails and formal documents.
• Polyglot Box: Instant code translation between 12+ languages.

💹 The Smart Grid (Financial)

• Asset Command: Programmable logic for portfolio management.
• Macro Net: Global M2 Money Supply vs. Asset correlation heatmap.
• Chain Pulse: Real-time TPS tracking for L1/L2 networks.
• Reg Radar: Sentiment analysis on regulatory news (SEC/MiCA).
• Market Widget: Real-time market data feeds and price tracking.
• Valuta Exchange: Currency converter with real-time exchange rates across 12+ currencies.

🛠️ Developer Optic

• Web Terminal: Sandboxed JavaScript REPL.
• Dev Optic: JWT decoding and Regex testing.
• Git Pulse: Pull Request monitoring dashboard.
• Widget Architect: AI-driven prototype generation for new widgets.
• CyberEditor: Advanced code editor with multi-tab support, templates, and AI-powered code generation/improvement for creating Omni-Grid widgets.
• Prompt Lab: Version-controlled prompt workspace with template variables, token/cost telemetry, and side-by-side provider comparisons.

🎨 Creative & Utility

• Aesthetic Engine: AI-generated UI theming based on text or image vibes.
• Sonic Architecture: Circle of Fifths theory tool with brown noise and a local playlist player. Includes a ⚡ Demo button that loads the Omni-Grid 2.0 Official Theme from Suno AI.
• Cipher Vault: Local hashing and UUID/Nanoid generation.
• Chroma Lab: Color palette generator with Tailwind-compatible shade variations.
• Clipboard Stream: Clipboard history manager with drag-and-drop support.
• Quantum Calc: Scientific calculator with expression parsing and history.
• Weather Station: Real-time weather conditions for any location.
• Signal Radio: Audio player with frequency-responsive visualizer. Includes an ⚡ Omni-Grid Theme Suno AI preset station.
• Suno Player: Dedicated player for the Omni-Grid 2.0 Official Theme — native audio playback with seek/volume controls, cover art, and an embedded Suno iframe view.

📊 Productivity & Research

• Focus HUD: Pomodoro timer and task tracking.
• Temporal Nexus: Time zone converter and world clock.
• Secure Calendar: Local-first event scheduling.
• Strategic Blueprint: Project planning canvas.
• News Feed: Aggregated news streams.
• Research Browser: In-app web browsing.
• PDF Viewer: Document reader and viewer.
• Help Desk: Comprehensive help system with Wiki, Q&A, and step-by-step guides.
• Sudoku Grid: Sudoku puzzle game with difficulty levels and timer.

0x03 // INITIALIZATION PROTOCOLS

Prerequisites

• Node.js 20+ (required; Vite 8 / Vitest use node:util styleText which requires Node 20+)
• Google Gemini API Key (Required for Neural Link features)

Installation

1. Clone the Repository

   git clone https://github.com/GizzZmo/Omni-Grid-2.0.git
   cd Omni-Grid-2.0

2. Install Dependencies

   npm install

3. Configure Environment Create a .env file in the root directory:

GEMINI_API_KEY=your_google_gemini_api_key_here
E2B_API_KEY=your_e2b_api_key_here

GEMINI_API_KEY powers Gemini-based assistants (Neural Scratchpad, WritePad, Polyglot Box, Widget Architect, etc.), while E2B_API_KEY is optional and used for sandboxed Python execution in the Web Terminal widget. You can also inject window.E2B_API_KEY at runtime if you prefer not to bake the sandbox key into the client bundle.

Note: The code also supports legacy API_KEY for backwards compatibility, but GEMINI_API_KEY is the recommended variable name.

4. Ignition

   npm run dev
   # Access via http://localhost:5173 (or pass -- --port 1234 to match the C++ server default)

Optional: C++ Static Server

If you prefer a standalone HTTP host, compile the lightweight C++ server and serve the built assets (or the root for dev artifacts):

Using npm scripts (recommended):

npm run build:all    # Build frontend assets and compile C++ server
npm run serve        # Run the compiled server (defaults to port 1234)
# Then open http://localhost:1234

Manual compilation:

make server          # or: g++ -std=c++17 -O2 server/omnigrid_server.cpp -o omnigrid_server
./omnigrid_server 1234   # port is optional; defaults to 1234
# Then open http://localhost:1234

The server automatically serves from dist/ (built assets) if it exists, or falls back to the root directory (for dev artifacts).

0x04 // ARCHITECTURE

• State Management: Zustand with localStorage persistence.
• Layout: react-grid-layout for draggable, resizable tiles.
• AI Core: @google/genai (Gemini 3.5 Flash/Pro).
• Styling: TailwindCSS with dynamic CSS variable injection.

0x04.1 // CI/CD PIPELINE

Omni-Grid features a comprehensive automated workflow system:

🔄 Continuous Integration

• Automated Testing: Vitest test suite with coverage reporting
• Automated Building: Multi-platform builds (Node.js 18.x, 20.x)
• Type Safety: TypeScript strict checking on every commit
• Code Quality: ESLint and Prettier validation
• Performance Monitoring: Build time and bundle size tracking

🔒 Security & Quality

• CodeQL Analysis: Automated security vulnerability scanning (JavaScript & C++)
• Dependency Auditing: Daily npm security audits with PR alerts
• Dependabot: Automated dependency updates with auto-merge for safe updates
• Test Coverage: Automatic coverage reports on PRs

📦 Release & Deployment

• Automated Releases: Tag-triggered release creation with SHA-256 checksums
• Documentation Deployment: Auto-deploy docs to GitHub Pages
• Performance Reports: PR-specific build performance analysis with warnings

🤖 Automation

• PR Labeling: Automatic categorization based on changes and size
• Welcome Bot: First-time contributor greeting and guidance
• Stale Management: Automated cleanup of inactive issues/PRs
• Status Dashboard: Real-time workflow health monitoring

View Complete Workflow Documentation | Testing Guide

0x04.2 // DEVELOPMENT COMMANDS

Testing

npm test              # Run tests in watch mode
npm run test:run      # Run tests once (CI mode)
npm run test:ui       # Launch visual test UI
npm run test:coverage # Generate coverage report

Code Quality

npm run lint          # Run ESLint
npm run lint:fix      # Auto-fix ESLint issues
npm run format        # Format code with Prettier
npm run format:check  # Check code formatting
npm run typecheck     # Run TypeScript type checking

Building

npm run build         # Build frontend (Vite)
npm run build:server  # Build C++ server
npm run build:all     # Build both frontend and server
npm run dev           # Start development server
npm run preview       # Preview production build

0x05 // KEYBOARD SHORTCUTS

Key Combo	Action
Cmd + K	Trigger AI Refine in Scratchpad
Drag & Drop	Transfer data between widgets (Cross-Talk Protocol)

For complete keyboard shortcuts reference, see Keyboard Shortcuts Guide.

---

0x06 // DOCUMENTATION

Comprehensive documentation is available in the docs/ folder:

📚 Quick Links

• Documentation Hub - Complete documentation index
• Getting Started Guide - Installation and setup
• Widget Development - Create custom widgets
• Architecture Overview - Technical deep-dive
• API Reference - Complete API documentation
• Configuration Guide - Settings and customization
• State Management - Zustand patterns
• Performance Report - Interactive performance benchmarks
• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions
• WIKI - Core concepts and philosophy
• GitHub Wiki (Home) - Quick navigation map and page links (publish from docs/wiki/)
• How-To Guide - Practical recipes

---

0x07 // ROADMAP

Want to know what's coming next? Check out our comprehensive development roadmap:

🗺️ DEVELOPMENT ROADMAP - Complete project roadmap with timelines, milestones, and contribution opportunities

Current Focus (Q1 2025)

• 🚧 Music player widget enhancement
• ✅ Code editor widget (CyberEditor with AI assistance)
• 🚧 AI chat widget (Gemini API)
• 🚧 Settings panel v2
• 🚧 Theme customization system
• 🚧 Widget marketplace foundation

See the full roadmap for detailed timelines, technical milestones, and how you can contribute!

---

Built by [Jon-Arve Constantine / GizzZmo]. Encrypted. Distributed. Free.