┌─────────────────────────────────────────────────────────────────────┐
│ APEX ECOSYSTEM TRUTH TABLE (Load into working memory)              │
├─────────────────────────────────────────────────────────────────────┤
│ Platform:     APEX OmniHub ("Intelligence Designed")               │
│ Domain:       apexomnihub.icu                                      │
│ Core Value:   Universal Orchestration (Web2 ↔ Web3 Semantic Bridge)│
│ Stack:        React 18 + Vite + TypeScript + Tailwind + shadcn UI  │
│ Backend:      Supabase (Auth, Storage, Edge Functions, Postgres)   │
│ Orchestrator: Temporal.io (Event Sourcing + Saga Pattern)          │
│ Security:     Guardian/Triforce + MAN Mode + Zero-Trust + RLS      │
│ Test Suite:   ARMAGEDDON (265 tests, 100% pass, Level 6 Adaptive)  │
│ Non-Negotiable: No vendor lock-in, no drift, no loops, no secrets  │
└─────────────────────────────────────────────────────────────────────┘

Building new feature?     → Section A: FEATURE DEVELOPMENT
Fixing a bug?             → Section B: BUG RESOLUTION PROTOCOL
Optimizing performance?   → Section C: PERFORMANCE ENGINEERING
Security hardening?       → Section D: SECURITY POSTURE
Writing tests?            → Section E: ARMAGEDDON TEST PROTOCOL
Deploying/DevOps?         → Section F: DEPLOYMENT & OPS
Architecture decision?    → Section G: ARCHITECTURE PATTERNS
Working on specific app?  → Section H: APP-SPECIFIC PATTERNS

□ Identify target module (OmniDash | OmniConnect | OmniLink | Guardian | Edge)
□ Check existing patterns in that module (don't reinvent)
□ Verify abstraction layer exists (no direct provider calls)
□ Confirm test strategy (unit + integration + chaos)
□ Load relevant type definitions

UI Component?
├─ Shared across apps → src/components/
├─ Page-specific → src/pages/{PageName}/components/
└─ shadcn primitive → src/components/ui/

Business Logic?
├─ API calls → src/lib/api/
├─ State management → src/contexts/ or src/stores/
├─ Utilities → src/lib/utils/
└─ Security → src/security/

Backend?
├─ Edge Function → supabase/functions/{name}/
├─ Workflow → orchestrator/workflows/
├─ Activity → orchestrator/activities/
└─ Migration → supabase/migrations/

Test?
├─ Unit → tests/{module}/
├─ E2E → tests/e2e/
├─ Chaos → tests/chaos/
└─ Security → tests/prompt-defense/

// src/components/{ComponentName}.tsx
import { FC, memo } from 'react';
import { cn } from '@/lib/utils';

interface {ComponentName}Props {
  /** Required: Describe purpose */
  requiredProp: string;
  /** Optional: Describe default behavior */
  optionalProp?: boolean;
  className?: string;
}

/**
 * {ComponentName} - One-line description
 * @example <{ComponentName} requiredProp="value" />
 */
export const {ComponentName}: FC<{ComponentName}Props> = memo(({
  requiredProp,
  optionalProp = false,
  className,
}) => {
  return (
    <div className={cn('base-styles', className)}>
      {/* Implementation */}
    </div>
  );
});

{ComponentName}.displayName = '{ComponentName}';

// src/hooks/use{HookName}.ts
import { useState, useCallback, useEffect } from 'react';

interface Use{HookName}Options {
  initialValue?: string;
}

interface Use{HookName}Return {
  value: string;
  setValue: (v: string) => void;
  isLoading: boolean;
  error: Error | null;
}

export function use{HookName}(options: Use{HookName}Options = {}): Use{HookName}Return {
  const [value, setValue] = useState(options.initialValue ?? '');
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  // Cleanup on unmount (prevent memory leaks)
  useEffect(() => {
    return () => {
      // Cleanup timers, subscriptions, etc.
    };
  }, []);

  return { value, setValue, isLoading, error };
}

1. REPRODUCE → Get exact steps, inputs, expected vs actual
2. ISOLATE   → Identify smallest code path that triggers bug
3. TRACE     → Follow data flow from input to failure point
4. IDENTIFY  → Name the root cause (not symptoms)
5. FIX       → Patch at root, not at symptom
6. VERIFY    → Regression test + add to ARMAGEDDON suite
7. DOCUMENT  → Update CHANGELOG, add test case comment

undefined

---

Slow API call?
├─ Add React Query caching → staleTime: 5 * 60 * 1000
├─ Check N+1 queries → Use Supabase .select('*, relation(*)')
└─ Add index → supabase/migrations/

Slow render?
├─ Add memo() to component
├─ Use useMemo/useCallback for expensive computations
└─ Lazy load with React.lazy + Suspense

Memory leak?
├─ Check useEffect cleanup
├─ Verify event listener removal
└─ Check timer/interval cleanup

// src/lib/api/{resource}.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { supabase } from '@/lib/supabase';

const STALE_TIME = 5 * 60 * 1000; // 5 minutes

export function use{Resource}s() {
  return useQuery({
    queryKey: ['{resource}s'],
    queryFn: async () => {
      const { data, error } = await supabase
        .from('{resource}s')
        .select('*')
        .order('created_at', { ascending: false });
      if (error) throw error;
      return data;
    },
    staleTime: STALE_TIME,
  });
}

export function useCreate{Resource}() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: async (payload: Create{Resource}Payload) => {
      const { data, error } = await supabase
        .from('{resource}s')
        .insert(payload)
        .select()
        .single();
      if (error) throw error;
      return data;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['{resource}s'] });
    },
  });
}

❌ NEVER commit secrets (API keys, tokens, passwords)
❌ NEVER trust user input without validation
❌ NEVER bypass RLS policies
❌ NEVER execute raw SQL from user input
❌ NEVER disable CSRF protection
❌ NEVER log PII to console in production

✅ ALWAYS use parameterized queries
✅ ALWAYS validate with Zod schemas
✅ ALWAYS use RLS for row-level access
✅ ALWAYS audit log security events
✅ ALWAYS use Guardian heartbeat for critical loops

// Use MAN Mode for high-risk actions
import { riskTriage } from '@/orchestrator/policies/man_policy';

const result = riskTriage({
  tool: 'delete_record',
  params: { id: recordId },
  context: { userId, sessionId }
});

if (result.lane === 'RED') {
  // Isolate and await human approval
  await createManTask(result);
  return { status: 'isolated', awaiting_approval: true };
}

// src/security/promptDefense.ts
import { evaluatePrompt } from './promptDefenseConfig';

// Always sanitize LLM inputs
function sanitizeUserInput(input: string): string {
  const result = evaluatePrompt(input);
  if (result.blocked) {
    auditLog.record({
      actionType: 'PROMPT_INJECTION_BLOCKED',
      metadata: { pattern: result.matchedPattern }
    });
    throw new SecurityError('Invalid input detected');
  }
  return result.sanitized;
}

// Verify device on every sensitive operation
import { deviceRegistry } from '@/zero-trust/deviceRegistry';

async function sensitiveOperation(userId: string, deviceId: string) {
  const device = await deviceRegistry.verify(userId, deviceId);
  if (device.status !== 'trusted') {
    throw new SecurityError('Device not trusted');
  }
  // Proceed with operation
}

tests/
├── chaos/                    # Chaos engineering tests
│   ├── battery.spec.ts       # Core chaos battery (21 tests)
│   ├── memory-stress.spec.ts # Memory leak detection (7 tests)
│   └── integration-stress.spec.ts # Integration stress (9 tests)
├── e2e/                      # End-to-end tests
│   ├── enterprise-workflows.spec.ts # Business flows (20 tests)
│   ├── errorHandling.spec.ts # Error scenarios (8 tests)
│   └── security.spec.ts      # Security tests (13 tests)
├── prompt-defense/           # Prompt injection tests
│   └── real-injection.spec.ts # Real-world attacks
└── {module}/                 # Unit tests per module

// tests/{module}/{feature}.spec.ts
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

describe('{Feature}', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  it('should {expected behavior} when {condition}', async () => {
    // Arrange
    const input = { /* test data */ };

    // Act
    const result = await featureUnderTest(input);

    // Assert
    expect(result).toMatchObject({ /* expected */ });
  });

  it('should handle error when {error condition}', async () => {
    // Arrange
    vi.spyOn(dependency, 'method').mockRejectedValue(new Error('fail'));

    // Act & Assert
    await expect(featureUnderTest({})).rejects.toThrow('fail');
  });
});

undefined

---

□ Build passes: npm run build
□ Type check passes: npm run typecheck
□ All tests pass: npm test
□ Security audit clean: npm run security:audit
□ No console.log in production code
□ Environment variables documented
□ Rollback plan documented

undefined

undefined

undefined

---

┌─────────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER (React + shadcn UI)                              │
│ - OmniDash (Navigation UI)                                          │
│ - Pages (Route-level components)                                    │
│ - Components (Reusable UI)                                          │
└────────────────────────┬────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────────────┐
│ APPLICATION LAYER (Hooks + Context + React Query)                   │
│ - AuthContext (Session management)                                  │
│ - useQuery/useMutation (Data fetching)                             │
│ - Business logic hooks                                              │
└────────────────────────┬────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────────────┐
│ INTEGRATION LAYER (Adapters - Single Port Rule)                     │
│ - Supabase adapter (auth, db, storage)                             │
│ - OmniLink adapter (cross-app orchestration)                       │
│ - Web3 adapter (wallet, contracts)                                 │
└────────────────────────┬────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────────────┐
│ ORCHESTRATION LAYER (Temporal.io)                                   │
│ - Event Sourcing (Canonical Data Model)                            │
│ - Saga Pattern (LIFO Compensation)                                 │
│ - Semantic Caching (70% cost reduction)                            │
│ - MAN Mode (Human-in-the-loop for RED lane)                        │
└────────────────────────┬────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────────────┐
│ SECURITY LAYER (Guardian/Triforce)                                  │
│ - Guardian heartbeats                                               │
│ - Zero-trust device registry                                        │
│ - Prompt injection defense                                          │
│ - RLS policies                                                      │
│ - Audit logging                                                     │
└─────────────────────────────────────────────────────────────────────┘

// ❌ BAD: Direct provider coupling
import { createClient } from '@supabase/supabase-js';
const data = await supabase.from('users').select('*');

// ✅ GOOD: Abstraction layer
// src/lib/database/interface.ts
interface Database {
  query<T>(table: string, options: QueryOptions): Promise<T[]>;
}

// src/lib/database/supabase.ts
export const supabaseDatabase: Database = {
  async query(table, options) {
    const { data } = await supabase.from(table).select(options.select);
    return data;
  }
};

// src/lib/database/index.ts
import { supabaseDatabase } from './supabase';
export const database: Database = supabaseDatabase; // Swap here for migration

src/lib/
├── supabase/           # Single port for Supabase
│   ├── index.ts        # Re-exports
│   ├── auth.ts         # Auth methods
│   ├── database.ts     # Query methods
│   └── storage.ts      # Storage methods
├── web3/               # Single port for Web3
│   ├── index.ts
│   ├── wallet.ts
│   └── contracts.ts
└── omnilink/           # Single port for OmniLink orchestration
    ├── index.ts
    └── events.ts

// Revolutionary icon-based navigation
// Location: src/components/OmniDashNavIconButton.tsx

// Pattern: Zero-overlap flexbox layout
<nav className="flex items-center justify-between">
  <OmniDashNavIconButton icon={Home} label="Dashboard" to="/" />
  <OmniDashNavIconButton icon={Settings} label="Settings" to="/settings" />
</nav>

// Mobile: Bottom tabs
// Desktop: Side navigation with tooltips

// Guardian heartbeat pattern
// Location: src/guardian/heartbeat.ts

import { startHeartbeat, getStatus } from '@/guardian/heartbeat';

// Start on app mount
useEffect(() => {
  const cleanup = startHeartbeat('main-loop', 30000); // 30s interval
  return cleanup;
}, []);

// Check status
const status = getStatus('main-loop');
// { loopName: 'main-loop', lastSeen: Date, ageMs: number, status: 'healthy' | 'stale' }

undefined

    try:
        # Execute steps with compensation tracking
        for step in plan.steps:
            result = await workflow.execute_activity(
                execute_tool,
                step,
                start_to_close_timeout=timedelta(seconds=30),
            )
            compensation_stack.append(step.compensation)
        
        return GoalResult(status="completed", events=events)
        
    except Exception as e:
        # LIFO compensation (rollback)
        for comp in reversed(compensation_stack):
            await workflow.execute_activity(compensate, comp)
        raise

---

□ Am I still solving the ORIGINAL task?
□ Have I introduced any provider lock-in?
□ Does this code have a test?
□ Is security considered (RLS, validation, audit)?
□ Would this pass ARMAGEDDON Level 6?

IF same error appears 3x → STOP, re-read Section B (Bug Protocol)
IF same code pattern rewritten 3x → STOP, extract to utility
IF task scope expanded 2x → STOP, confirm with user
IF file touched 5x without progress → STOP, architectural issue

undefined

---

✅ Code compiles: npm run build passes
✅ Types valid: npm run typecheck passes
✅ Tests pass: npm test passes
✅ Security clean: npm run security:audit clean
✅ No drift: Original task accomplished
✅ Documented: CHANGELOG updated if applicable
✅ Portable: No new vendor lock-in introduced