designOS Agent Context - ZOE Solar Accounting OCR

🎯 Project Overview

ZOE Solar Accounting OCR - AI-powered document processing with designOS design system

Core Technologies:

• React 19 + TypeScript
• designOS Design System (Dark-first architecture)
• Better Upload (File upload pipeline)
• Google GenAI (Document analysis)
• Supabase (Storage & Database)
• Tailwind CSS v4

🎨 designOS Design System

Color Palette

/* Core Colors */
--color-primary: #0066ff; /* Actions, Links */
--color-secondary: #ff6b00; /* Highlights, Alerts */
--color-accent: #00d4ff; /* Emphasis */

/* Semantic Colors */
--color-success: #00cc66; /* Positive */
--color-warning: #ffb020; /* Caution */
--color-error: #ff4757; /* Destructive */

/* Dark Mode Native */
--color-background: #0a0e14; /* Dark base */
--color-surface: #151a23; /* Cards, Panels */
--color-surface-hover: #1e2532; /* Hover states */
--color-border: #2a3142; /* Borders */

/* Text Colors */
--color-text: #e6edf3; /* Primary text */
--color-text-muted: #8b949e; /* Secondary text */
--color-text-inverted: #0a0e14; /* Inverted text */

Spacing Scale

--spacing-xs: 4px;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
--spacing-xl: 32px;
--spacing-2xl: 48px;
--spacing-3xl: 64px;

Component Library

Available Components:

• Button - 5 variants, 3 sizes, loading states
• Input - 3 variants, 3 sizes, validation states
• Card - 4 variants, 5 padding sizes
• Layout - Stack, Grid, Flex, Center, Container

Usage Pattern:

import { Button, Card, Stack } from '@/components/designOS';

<Stack gap="md">
  <Card variant="elevated" padding="lg">
    <Button variant="primary" size="md">
      Upload Document
    </Button>
  </Card>
</Stack>;

📤 Better Upload Integration

Upload Pipeline

1. File Read → Base64 conversion
2. Gemini Analysis → Document extraction
3. Normalization → Standardize data
4. Security Check → Private document detection
5. Rule Engine → Accounting rules application
6. ID Generation → ZOE invoice ID
7. Hash Computation → Duplicate detection
8. Supabase Upload → Storage
9. Database Save → Record creation
10. Monitoring → Metrics & error tracking

Upload Handler

// src/services/betterUploadServer.ts
export const zoeUploadHandler: UploadHandler = async (file, metadata) => {
  // Complete processing pipeline
  // Returns: UploadResult with success/error status
};

🏗️ File Structure

src/
├── components/
│   ├── designOS/           # Design system components
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   ├── Card.tsx
│   │   ├── Layout.tsx
│   │   └── index.ts
│   ├── UploadArea.tsx      # Main upload interface
│   └── ErrorBoundary.tsx   # Error handling
├── services/
│   ├── betterUploadServer.ts  # Upload pipeline
│   ├── geminiService.ts       # AI analysis
│   ├── supabaseService.ts     # Database
│   └── monitoringService.ts   # Metrics
├── styles/
│   └── global.css          # designOS tokens
└── App.tsx                 # Main application

🔧 Development Commands

# Development
npm run dev              # Start dev server
npm run typecheck        # TypeScript check
npm run build            # Production build
npm run preview          # Preview build

# Quality
npm run lint             # ESLint check
npm run format           # Prettier format
npm test                 # Run tests

# Full verification
npm run check            # typecheck + build

🎯 Key Patterns

1. Always Use designOS Components

// ✅ CORRECT
import { Button, Card } from '@/components/designOS';
<Button variant="primary">Click</Button>

// ❌ WRONG
<button className="bg-blue-500">Click</button>

2. Use designOS Tokens

// ✅ CORRECT
<div style={{ gap: 'var(--spacing-md)' }}>

// ❌ WRONG
<div style={{ gap: '16px' }}>

3. Dark-First Styling

/* ✅ CORRECT - Dark mode native */
@theme {
  --color-background: #0a0e14;
}

/* ❌ WRONG - Light mode with dark override */
body {
  background: white;
}
@media (prefers-color-scheme: dark) {
  body {
    background: #0a0e14;
  }
}

🚨 Critical Rules

1. Never use @apply with non-existent utilities
2. Always use MCP tools (Serena, Tavily) for file operations
3. Keep files under 300 lines (SRP compliance)
4. TypeScript strict mode - no any types
5. DesignOS compliance - all new components must use tokens

📈 Success Metrics

• ✅ TypeScript: 0 errors
• ✅ Build: < 5 seconds
• ✅ Bundle: < 500 kB
• ✅ DesignOS: 100% compliance
• ✅ Upload: Complete pipeline working
• ✅ Tests: 78 unit tests passing

Last Updated: 2026-02-13
Status: Production Ready 🚀

📝 February 2026 Updates

2026-02-13

• TypeScript: 0 errors ✅
• Build: 8.7s ✅
• Tests: 78/78 passing ✅
• Production ready verified