ARCHITECTURE // SYSTEM BLUEPRINT

[ DOCUMENTATION: ARCHITECTURE.MD ]
[ STATUS: TECHNICAL DEEP-DIVE ACTIVE ]

🏗️ OVERVIEW

Omni-Grid is a local-first, modular Super App built on React with a focus on privacy, extensibility, and high-density information display. The architecture follows a hub-and-spoke model where widgets are independent modules coordinated by a central state manager.

See screenshots for visual examples of the dashboard and individual widget categories.

Core Principles

Local-First: All data persists in browser localStorage. No cloud dependencies.
Widget Isolation: Each widget is self-contained with minimal coupling.
Cross-Talk Protocol: Widgets communicate via drag-and-drop events.
AI Integration: Direct client-to-API calls (no proxy server).
Responsive Grid: Dynamic layout with drag/resize capabilities.

Widget Catalogue (43 modules)

Category	Widget IDs
Neural Suite	`SCRATCHPAD`, `WRITEPAD`, `POLYGLOT`, `ARCHITECT`, `NEURAL_CHAT`
Smart Grid	`ASSET`, `MACRO_NET`, `CHAIN_PULSE`, `REG_RADAR`, `MARKET`, `VALUTA`
Developer Optic	`WEB_TERMINAL`, `DEV_OPTIC`, `GIT_PULSE`, `DOCU_HUB`, `PROJECT_TRACKER`, `CYBER_EDITOR`, `PROMPT_LAB`
Creative & Utility	`THEME_ENGINE`, `SONIC`, `CIPHER_VAULT`, `CHROMA_LAB`, `CLIPBOARD`, `CALC`, `WEATHER`, `RADIO`, `SUNO_PLAYER`
Productivity & Research	`FOCUS_HUD`, `TEMPORAL`, `SECURE_CALENDAR`, `STRATEGIC`, `NEWS_FEED`, `RESEARCH_BROWSER`, `PDF_VIEWER`, `HELP`, `CIPHER_PAD`
System	`TRANSFORMER`, `SYSTEM`, `SUDOKU`, `GHOST`
Marketplace & Community	`MARKETPLACE`, `COMMUNITY_PORTAL`
Orchestration & Browser	`MULTI_AGENT_HUB`, `BROWSER_WIDGET`

📐 SYSTEM ARCHITECTURE

High-Level Diagram

┌─────────────────────────────────────────────────────────┐
│                    Browser Environment                   │
│  ┌─────────────────────────────────────────────────┐   │
│  │              App.tsx (Root)                      │   │
│  │  - Global Controls                               │   │
│  │  - Dock                                          │   │
│  │  - Background Effects                            │   │
│  └───────────────┬─────────────────────────────────┘   │
│                  │                                       │
│  ┌───────────────▼─────────────────────────────────┐   │
│  │       GridContainer (Layout Engine)              │   │
│  │  - react-grid-layout wrapper                     │   │
│  │  - Widget instantiation                          │   │
│  │  - Drag & Drop handlers                          │   │
│  └───┬──────────────────────────────────────────┬──┘   │
│      │                                           │       │
│  ┌───▼─────────┐  ┌──────────────┐  ┌──────────▼───┐  │
│  │  Widget 1   │  │   Widget 2   │  │   Widget N   │  │
│  │ (WidgetShell│  │ (WidgetShell │  │ (WidgetShell │  │
│  │  + Content) │  │  + Content)  │  │  + Content)  │  │
│  └─────────────┘  └──────────────┘  └──────────────┘  │
│         ▲                  ▲                  ▲         │
│         │                  │                  │         │
│  ┌──────┴──────────────────┴──────────────────┴─────┐  │
│  │           Zustand Store (store.ts)               │  │
│  │  - Global state                                  │  │
│  │  - Widget visibility                             │  │
│  │  - Layouts (responsive breakpoints)              │  │
│  │  - Settings, theme, content                      │  │
│  │  - localStorage sync                             │  │
│  └──────────────────────────────────────────────────┘  │
│         ▲                                               │
│         │                                               │
│  ┌──────┴───────────────────────────────────────────┐  │
│  │          Browser localStorage                     │  │
│  │  Key: "omni-grid-storage"                        │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

🧩 CORE COMPONENTS

1. App.tsx (Root Component)

Responsibilities:

Render global header with controls
Manage system-level state (freeze, lock, compact mode)
Handle backup/restore operations
Render dock with widget toggles
Coordinate background effects (Matrix Rain, gradients)

Key Features:

Freeze System: Suspends all interactions for safe backups
Auto-Organize: Calls AI service to optimize layout
Theme Application: Injects CSS variables dynamically

State Subscriptions:

const visibleWidgets = useAppStore(s => s.visibleWidgets);
const settings = useAppStore(s => s.settings);
const theme = useAppStore(s => s.theme);
const layouts = useAppStore(s => s.layouts);

2. GridContainer.tsx (Layout Manager)

Responsibilities:

Wrap react-grid-layout with responsive breakpoints
Instantiate visible widgets based on visibleWidgets array
Handle layout change events
Implement drag-and-drop Cross-Talk protocol

Grid Configuration:

breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
rowHeight={30}
compactType={isCompact ? 'vertical' : null}

Widget Registry: All widgets are registered in widgetComponents object:

const widgetComponents: Record<WidgetType, JSX.Element> = {
  SCRATCHPAD: <WidgetShell id="SCRATCHPAD" title="Neural Scratchpad" ...>
    <NeuralScratchpad />
  </WidgetShell>,
  // ... other widgets
};

3. WidgetShell.tsx (Widget Wrapper)

Responsibilities:

Provide consistent header with icon, title, accent color
Handle minimize/maximize states
Provide close button
Apply consistent styling

Props Interface:

interface WidgetShellProps {
  id: string;
  title: string;
  icon: React.ReactNode;
  accentColor: string;
  children: React.ReactNode;
  className?: string;
}

4. store.ts (State Management)

Technology: Zustand 5 with localStorage persistence middleware

State Structure:

interface AppState {
  // Visibility — plain string IDs to support dynamic/marketplace widgets
  visibleWidgets: string[];

  // Layout (lg breakpoint only; responsive scaling handled by react-grid-layout)
  layouts: { lg: GridItemData[] };

  // Widget-specific data
  scratchpadContent: string;
  tasks: Task[];
  tickers: string[];
  writePadContent: string;
  weatherLocation: string;
  clipboardHistory: string[];
  cyberEditorTabs: CyberEditorTab[];
  promptLibrary: PromptTemplate[];

  // System settings
  settings: {
    geminiApiKey: string;
    e2bApiKey: string;
    scanlines: boolean;
    sound: boolean;
    startupBehavior: 'restore' | 'default' | 'empty';
  };

  // Theme
  theme: AppTheme;

  // UI state
  isLayoutLocked: boolean;
  isCompact: boolean;
  ghostWidget: GhostData | null;
  isCmdPaletteOpen: boolean;
  isSettingsPanelOpen: boolean;

  // Marketplace
  installedWidgets: Record<string, string>;
  availableUpdates: string[];

  // Actions
  toggleWidget: (widgetId: string) => void;
  updateLayout: (newLayout: GridItemData[]) => void;
  setGlobalState: (state: Partial<AppState>) => void;
  resetAll: () => void;
  // ... other actions
}

Persistence:

persist(
  (set, get) => ({
    /* state */
  }),
  {
    name: 'omni-grid-storage',
    storage: createJSONStorage(() => localStorage),
  }
);

🔄 DATA FLOW

Typical User Interaction Flow

User Action (e.g., toggle widget)
    ↓
Dock Button onClick
    ↓
toggleWidget(widgetId) called
    ↓
Zustand updates visibleWidgets array
    ↓
GridContainer re-renders
    ↓
New widget appears in grid
    ↓
State persisted to localStorage

Cross-Talk Protocol Flow

User drags data from Widget A
    ↓
onDragStart captures data
    ↓
User drops on Widget B
    ↓
onDrop in Widget B receives data
    ↓
Widget B processes/displays data
    ↓
No central state mutation (decoupled)

🧠 AI INTEGRATION ARCHITECTURE

Neural Link (Gemini API)

Service Layer: services/geminiService.ts

Flow:

Widget (e.g., NeuralScratchpad)
    ↓
User clicks "Refine" button
    ↓
callGemini(prompt, content) invoked
    ↓
Direct HTTPS request to api.generativeai.google.com
    ↓
Response streamed back
    ↓
Widget updates with AI output
    ↓
Saved to localStorage via Zustand

Privacy Model:

API key stored in localStorage (user-controlled)
No intermediate server (direct client ↔ Google)
No prompt logging by Omni-Grid (Google's privacy policy applies)

Models Used:

gemini-3-flash-preview - Fast operations (summarize, translate, refine)
gemini-2.5-pro-preview - Complex operations (code generation, analysis)

🎨 STYLING ARCHITECTURE

Technology Stack

TailwindCSS - Utility-first CSS framework
CSS Variables - Dynamic theming
Custom Classes - Special effects (scanlines, scrollbars)

Theme System

Dynamic CSS Injection:

useEffect(() => {
  const root = document.documentElement;
  root.style.setProperty('--color-bg', theme.colors.background);
  root.style.setProperty('--color-primary', theme.colors.primary);
  // ... other properties
}, [theme]);

Aesthetic Engine Integration:

User can generate themes via AI (text/image input)
Presets available (Cyberpunk, Neon, Minimal, etc.)
Custom color pickers for manual tweaking
Themes persist in Zustand store

📦 BUILD & DEPLOYMENT

Development Setup

npm run dev          # Vite dev server (port 5173)
npm run build        # Production build → dist/
npm run preview      # Preview production build

Vite Configuration

Key Settings:

// vite.config.ts
export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
});

Production Build Output

dist/
├── index.html           # Entry point
├── assets/
│   ├── index.[hash].js  # Bundled JavaScript
│   ├── index.[hash].css # Bundled CSS
│   └── ...              # Fonts, images

Deployment:

Static files only
No server required
Can be hosted on: GitHub Pages, Netlify, Vercel, S3, etc.
HTTPS recommended (for API calls and localStorage security)

🔐 SECURITY ARCHITECTURE

Data Privacy

Local-First: No data leaves the browser except AI API calls
No Analytics: No tracking, telemetry, or third-party scripts
API Key Management: User-controlled, stored in localStorage only
No Cookies: State management via localStorage only

Content Security Policy (Recommended)

For production deployment:

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; 
               connect-src 'self' https://generativelanguage.googleapis.com;
               style-src 'self' 'unsafe-inline';
               script-src 'self';"
/>

localStorage Security

Sensitive data (API keys) stored in plain text in localStorage
Recommendation: Use a strong device/browser password
Future enhancement: Add optional password protection layer

📊 PERFORMANCE CONSIDERATIONS

Optimization Strategies

Selective Re-renders:

// Individual selectors to prevent unnecessary re-renders
const visibleWidgets = useAppStore(s => s.visibleWidgets);
// Instead of: const state = useAppStore();

Lazy Loading:
- Widgets only render when visible
- Heavy components (PDFViewer, ResearchBrowser) load on-demand
Virtualization:
- Grid layout handles large numbers of widgets efficiently
- Widgets outside viewport still consume memory (trade-off for instant visibility)
localStorage Throttling:
- Zustand middleware batches updates
- Prevents excessive writes on rapid state changes

Browser Compatibility

Minimum Requirements:

Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
localStorage support (required)
ES2020+ support
CSS Grid and Flexbox

🧪 TESTING ARCHITECTURE

Current State

Vitest test suite located in the test/ directory
Tests run with npm run test:run (CI mode) or npm test (watch mode)
Coverage reports generated via npm run test:coverage

Testing Strategy

Unit Tests:

Widget components (React Testing Library + Vitest)
Utility functions
Zustand store actions

Integration Tests:

Widget communication (Cross-Talk)
Layout persistence
Backup/restore functionality

E2E Tests:

Playwright or Cypress
Critical user journeys

🔌 EXTENSIBILITY

Adding New Widgets

See Widget Development Guide for details.

Key Extension Points:

types.ts - Add new WidgetType
widgets/ - Create component
GridContainer.tsx - Register widget
App.tsx - Add dock item (optional)
store.ts - Add widget-specific state (optional)

Custom Services

Create new files in services/:

// services/myService.ts
export const myFunction = async (param: string) => {
  // Implementation
};

Import and use in widgets:

import { myFunction } from '../services/myService';

Styling Extensions

Add custom Tailwind classes in index.css:

@layer utilities {
  .my-custom-class {
    /* styles */
  }
}

📈 SCALABILITY

Widget Limits

Practical Limits:

~20-30 widgets per grid (browser performance)
~50-100 items in a single widget (e.g., task list)
localStorage limit: ~5-10MB (browser-dependent)

Optimization for Scale:

Implement virtual scrolling for large lists
Paginate data-heavy widgets
Consider IndexedDB for very large datasets

Multi-User Considerations

Current architecture is single-user, single-device.

For Multi-User:

Add backend API for state sync
Implement authentication layer
Replace localStorage with API calls
Add conflict resolution for concurrent edits

🗺️ TECHNOLOGY ROADMAP

Current Stack (v2.0)

React 19.2.4
Zustand 5.0.12
react-grid-layout 1.4.4
Vite 8.0.0
TailwindCSS (via CDN in index.html)

Future Considerations

TypeScript strict mode enforcement
Component library (shadcn/ui)
Testing framework (Vitest + RTL)
PWA capabilities (offline mode)
Electron wrapper (desktop app)

📚 FURTHER READING

State Management Guide - Deep dive into Zustand patterns
Widget Development - Build custom widgets
API Reference - Complete API docs
Configuration - Advanced settings

Architecture is not just about structure—it's about philosophy.

← Back to Documentation Hub

FilesExpand file tree

architecture.md

Latest commit

History

architecture.md

File metadata and controls

ARCHITECTURE // SYSTEM BLUEPRINT

🏗️ OVERVIEW

Core Principles

Widget Catalogue (43 modules)

📐 SYSTEM ARCHITECTURE

High-Level Diagram

🧩 CORE COMPONENTS

1. App.tsx (Root Component)

2. GridContainer.tsx (Layout Manager)

3. WidgetShell.tsx (Widget Wrapper)

4. store.ts (State Management)

🔄 DATA FLOW

Typical User Interaction Flow

Cross-Talk Protocol Flow

🧠 AI INTEGRATION ARCHITECTURE

Neural Link (Gemini API)

🎨 STYLING ARCHITECTURE

Technology Stack

Theme System

📦 BUILD & DEPLOYMENT

Development Setup

Vite Configuration

Production Build Output

🔐 SECURITY ARCHITECTURE

Data Privacy

Content Security Policy (Recommended)

localStorage Security

📊 PERFORMANCE CONSIDERATIONS

Optimization Strategies

Browser Compatibility

🧪 TESTING ARCHITECTURE

Current State

Testing Strategy

🔌 EXTENSIBILITY

Adding New Widgets

Custom Services

Styling Extensions

📈 SCALABILITY

Widget Limits

Multi-User Considerations

🗺️ TECHNOLOGY ROADMAP

Current Stack (v2.0)

Future Considerations

📚 FURTHER READING