# Locus Executive OS - Full Architecture & Capability Specification

## 1. System Overview

Locus Executive OS is a cognitive operating system engineered for founders, CEOs, and executive leaders. Built for extreme cognitive bandwidth, it transforms unstructured, rapid-fire mental streams into highly structured, prioritized operational execution across personal and organizational horizons.

- **Production URL**: https://locus.demiurx.com
- **Hosting Infrastructure**: Google Cloud Firebase Hosting (`locus-executive-os-892`)
- **Direct Executive Inquiries**: locus@demiurx.com
- **Direct WhatsApp Line**: +1 5136453848 (https://wa.me/15136453848)

---

## 2. Core Architecture & Stack

### Client-Side Architecture
- **Runtime**: React 19 (TypeScript strict mode)
- **Bundler & Tooling**: Vite 6, Tailwind CSS (modern slate dark-mode palette)
- **Local Storage Engine**: LocalForage (IndexedDB fallback to WebSQL/LocalStorage)
- **Audio Capture**: Web Audio API / MediaRecorder for real-time executive voice memo transcription
- **Keyboard Engine**: Global command palette listeners (`Ctrl/Cmd+K`, `Esc`, `Ctrl/Cmd+Enter`)

### Cloud & Synchronization Engine
- **Identity & Access Management**: Firebase Authentication (verified email gate, enterprise password security, brute-force lockout throttling)
- **Realtime Database & Sync**: Firebase Realtime Database / Firestore with optimistic local writes and offline-first queue resolution
- **Product Telemetry**: PostHog US Cloud (`https://us.i.posthog.com`) with privacy-by-design (zero recording of confidential thoughts, masked user input, no screen session recording)

---

## 3. Data Schema & Domain Entities

### ThoughtItem (The Atomic Executive Unit)
```typescript
export interface ThoughtItem {
  id: string;
  rawText: string;
  category: 'TODO' | 'IDEA' | 'PROJECT' | 'STREAM' | 'GOAL' | 'MEETING' | 'HABIT';
  status: 'inbox' | 'active' | 'completed' | 'archived';
  scope: 'personal' | 'group';
  workgroupId?: string;
  createdAt: number;
  updatedAt: number;
  priority?: 'urgent_important' | 'important_not_urgent' | 'urgent_not_important' | 'neither';
  scheduledDate?: string;
  dueDate?: string;
  tags?: string[];
  subtasks?: Array<{ id: string; text: string; completed: boolean }>;
  auditTrail?: Array<{
    timestamp: number;
    action: 'created' | 'status_changed' | 'moved_workspace' | 'priority_changed' | 'updated';
    actorId: string;
    actorEmail?: string;
    details?: string;
  }>;
}
```

### Workgroup (Collaborative Executive Workspace)
```typescript
export interface Workgroup {
  id: string;
  name: string;
  description?: string;
  ownerId: string;
  members: Record<string, {
    email: string;
    role: 'owner' | 'admin' | 'member' | 'viewer';
    joinedAt: number;
  }>;
  createdAt: number;
  updatedAt: number;
}
```

---

## 4. Key Functional Modules

### 4.1 Omnibar & Cognitive Decomposition
- Instant capture dialog accessible globally via `Ctrl/Cmd+K`.
- Real-time AI categorization using Google Gemini to parse intents, extract deadlines, identify potential subtasks, and tag context automatically.
- Fallback heuristic parsing for zero-latency offline operation.

### 4.2 Executive Matrix & Horizon View
- Eisenhower matrix quadrant categorization allowing fast triage.
- Horizon timeline visualization organizing long-running strategic initiatives across quarter, month, and week milestones.

### 4.3 Card Modal with Real-time Save & Audit Trail
- Non-blocking debounced auto-save with instant manual flush (`✓ OK` button and `Ctrl/Cmd+Enter`).
- Real-time indicator displaying save transitions (`Saving...` -> `✓ Saved`).
- Comprehensive audit log tracking card lifecycle, mobility between personal and workgroup workspaces, and membership edits.

### 4.4 Telemetry & Privacy Standards
- Strict executive privacy policy: raw thoughts and sensitive strings are NEVER sent to telemetry.
- Telemetry events are strictly categorical: `thought_captured` (capturing category, scope, character length bracket), `card_updated`, `card_moved_workspace`, `workgroup_switched`, `view_changed`.
- Account configuration: PostHog Cloud (US region).

---

## 5. Contact & Support Channels

For technical partnerships, LLM integrations, or enterprise inquiries:
- Contact Email: locus@demiurx.com
- Direct Executive WhatsApp: +1 5136453848 (https://wa.me/15136453848)
- Demiurx Systems: https://demiurx.com