aios-core 2.1.5 → 2.2.0

package/.aios-core/product/data/roi-calculation-guide.md

@@ -0,0 +1,142 @@
+# ROI Calculation Guide
+
+**Purpose:** How to calculate real cost savings from design system
+**Agent:** Brad / Design System
+**Method:** Pattern-weighted cost analysis
+
+---
+
+## Formula Base
+
+```python
+monthly_cost = patterns × hours_per_pattern × hourly_rate
+
+annual_savings = (cost_before - cost_after) × 12
+
+roi_ratio = annual_savings / implementation_cost
+```
+
+---
+
+## Pattern Weights (Critical!)
+
+**Problem:** Not all patterns cost the same to maintain.
+
+**Solution:** Weight by complexity and change frequency.
+
+```python
+pattern_weights = {
+    'button': 1.0,        # Baseline (2h/month)
+    'input': 1.5,         # Validation logic
+    'form': 4.0,          # Complex state, validation
+    'modal': 2.0,         # Overlay logic, accessibility
+    'dropdown': 2.5,      # Complex interactions
+    'card': 0.8,          # Mostly layout
+    'color': 0.2,         # Trivial (just CSS)
+    'spacing': 0.3,       # Low complexity
+    'typography': 0.5,    # Medium complexity
+}
+
+weighted_hours = sum(
+    pattern_count × weight × base_hours
+    for pattern, count in patterns.items()
+)
+```
+
+---
+
+## Example Calculation
+
+### Before Consolidation
+
+```yaml
+patterns:
+  buttons: 47 × 1.0 = 47 units
+  inputs: 23 × 1.5 = 34.5 units
+  forms: 12 × 4.0 = 48 units
+  colors: 89 × 0.2 = 17.8 units
+  spacing: 19 × 0.3 = 5.7 units
+
+total_units: 153 units
+hours_per_unit: 2h/month
+monthly_hours: 306h
+hourly_rate: $150/h
+monthly_cost: $45,900
+annual_cost: $550,800
+```
+
+### After Consolidation
+
+```yaml
+patterns:
+  buttons: 3 × 1.0 = 3 units
+  inputs: 5 × 1.5 = 7.5 units
+  forms: 3 × 4.0 = 12 units
+  colors: 12 × 0.2 = 2.4 units
+  spacing: 7 × 0.3 = 2.1 units
+
+total_units: 27 units
+monthly_hours: 54h
+monthly_cost: $8,100
+annual_cost: $97,200
+```
+
+### Savings
+
+```yaml
+monthly_savings: $37,800
+annual_savings: $453,600
+
+implementation_cost: $15,000
+
+roi_ratio: 30.2x
+breakeven: 0.4 months (12 days)
+```
+
+---
+
+## Conservative vs Aggressive Estimates
+
+### Conservative (Recommended)
+
+- Base hours: 2h/month
+- Hourly rate: $150/h
+- Include only direct maintenance (bugs, updates)
+
+### Aggressive
+
+- Base hours: 3h/month
+- Include code reviews, discussions, decision time
+- Include opportunity cost of inconsistency
+
+**Brad recommends:** Use conservative numbers for stakeholders.
+
+---
+
+## Beyond Direct Cost
+
+### Velocity Impact
+
+```python
+feature_velocity_multiplier = 3-6x
+
+# Conservative estimate: 4x
+time_saved_per_feature = 75%  # 16h → 4h
+
+features_per_sprint = baseline_features × 4
+```
+
+### Quality Improvements
+
+- Fewer bugs (consistent patterns)
+- Better accessibility (system enforces WCAG)
+- Easier onboarding (single source of truth)
+
+**Hard to quantify but real value.**
+
+---
+
+## Brad says:
+
+"Conservative ROI = credible ROI.
+Underpromise, overdeliver."

package/.aios-core/product/data/supabase-patterns.md

@@ -0,0 +1,330 @@
+# Supabase Architecture Patterns
+
+**Purpose:** Reference guide for Supabase implementation patterns
+**Agent:** Dan (Data Engineer)
+**Platform:** Supabase (PostgreSQL + Auth + Storage + Realtime)
+
+---
+
+## PROJECT STRUCTURE
+
+### Recommended Organization
+```
+project/
+├── supabase/
+│   ├── migrations/         # Database migrations
+│   │   ├── 00001_initial_schema.sql
+│   │   └── 00002_add_rls_policies.sql
+│   ├── functions/          # Edge Functions
+│   │   └── function-name/
+│   │       └── index.ts
+│   ├── seed.sql            # Seed data for development
+│   └── config.toml         # Supabase CLI config
+├── src/
+│   ├── lib/
+│   │   └── supabase.ts     # Supabase client initialization
+│   └── types/
+│       └── database.ts     # Generated types from schema
+└── .env.local              # Environment variables
+```
+
+---
+
+## CLIENT INITIALIZATION
+
+### Browser Client (Public)
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database'
+
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+)
+```
+
+### Server Client (Service Role)
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '@/types/database'
+
+// Only use server-side, never expose to client
+export const supabaseAdmin = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  {
+    auth: {
+      autoRefreshToken: false,
+      persistSession: false
+    }
+  }
+)
+```
+
+---
+
+## AUTHENTICATION PATTERNS
+
+### Sign Up with Email
+```typescript
+const { data, error } = await supabase.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    data: {
+      full_name: 'User Name',
+      // Additional user metadata
+    }
+  }
+})
+```
+
+### Sign In
+```typescript
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password'
+})
+```
+
+### OAuth Provider
+```typescript
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'github',
+  options: {
+    redirectTo: `${window.location.origin}/auth/callback`
+  }
+})
+```
+
+### Session Management
+```typescript
+// Get current session
+const { data: { session } } = await supabase.auth.getSession()
+
+// Listen to auth changes
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_IN') {
+    // Handle sign in
+  } else if (event === 'SIGNED_OUT') {
+    // Handle sign out
+  }
+})
+```
+
+---
+
+## DATABASE PATTERNS
+
+### Type-Safe Queries
+```typescript
+// Fetch with type safety
+const { data, error } = await supabase
+  .from('profiles')
+  .select('id, username, avatar_url')
+  .eq('id', userId)
+  .single()
+
+// Insert with return
+const { data, error } = await supabase
+  .from('posts')
+  .insert({ title, content, author_id: userId })
+  .select()
+  .single()
+
+// Update
+const { data, error } = await supabase
+  .from('profiles')
+  .update({ username: newUsername })
+  .eq('id', userId)
+  .select()
+  .single()
+
+// Delete
+const { error } = await supabase
+  .from('posts')
+  .delete()
+  .eq('id', postId)
+```
+
+### Relationships
+```typescript
+// Fetch with foreign key relation
+const { data, error } = await supabase
+  .from('posts')
+  .select(`
+    id,
+    title,
+    content,
+    author:profiles(id, username, avatar_url)
+  `)
+  .eq('id', postId)
+  .single()
+```
+
+### Pagination
+```typescript
+const pageSize = 10
+const page = 1
+
+const { data, count, error } = await supabase
+  .from('posts')
+  .select('*', { count: 'exact' })
+  .order('created_at', { ascending: false })
+  .range((page - 1) * pageSize, page * pageSize - 1)
+```
+
+---
+
+## REALTIME PATTERNS
+
+### Subscribe to Changes
+```typescript
+const channel = supabase
+  .channel('posts-changes')
+  .on(
+    'postgres_changes',
+    {
+      event: '*',
+      schema: 'public',
+      table: 'posts',
+      filter: `author_id=eq.${userId}`
+    },
+    (payload) => {
+      console.log('Change received:', payload)
+    }
+  )
+  .subscribe()
+
+// Cleanup
+channel.unsubscribe()
+```
+
+### Presence (Online Status)
+```typescript
+const channel = supabase.channel('room:lobby')
+
+channel
+  .on('presence', { event: 'sync' }, () => {
+    const state = channel.presenceState()
+    console.log('Online users:', state)
+  })
+  .subscribe(async (status) => {
+    if (status === 'SUBSCRIBED') {
+      await channel.track({ user_id: userId, online_at: new Date() })
+    }
+  })
+```
+
+---
+
+## STORAGE PATTERNS
+
+### Upload File
+```typescript
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .upload(`${userId}/avatar.png`, file, {
+    cacheControl: '3600',
+    upsert: true
+  })
+```
+
+### Get Public URL
+```typescript
+const { data } = supabase.storage
+  .from('avatars')
+  .getPublicUrl(`${userId}/avatar.png`)
+
+const publicUrl = data.publicUrl
+```
+
+### Signed URL (Private)
+```typescript
+const { data, error } = await supabase.storage
+  .from('private-docs')
+  .createSignedUrl(`${userId}/document.pdf`, 3600) // 1 hour
+```
+
+---
+
+## EDGE FUNCTIONS
+
+### Function Structure
+```typescript
+// supabase/functions/hello-world/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+serve(async (req) => {
+  const supabaseClient = createClient(
+    Deno.env.get('SUPABASE_URL') ?? '',
+    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+    {
+      global: {
+        headers: { Authorization: req.headers.get('Authorization')! }
+      }
+    }
+  )
+
+  // Get user from JWT
+  const { data: { user } } = await supabaseClient.auth.getUser()
+
+  return new Response(
+    JSON.stringify({ message: `Hello ${user?.email}` }),
+    { headers: { 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+---
+
+## TYPE GENERATION
+
+### Generate Types from Schema
+```bash
+# Install Supabase CLI
+npm install -g supabase
+
+# Generate types
+supabase gen types typescript --project-id your-project-id > src/types/database.ts
+
+# Or from local
+supabase gen types typescript --local > src/types/database.ts
+```
+
+### Usage
+```typescript
+import type { Database } from '@/types/database'
+
+type Profile = Database['public']['Tables']['profiles']['Row']
+type InsertProfile = Database['public']['Tables']['profiles']['Insert']
+type UpdateProfile = Database['public']['Tables']['profiles']['Update']
+```
+
+---
+
+## ERROR HANDLING
+
+### Standard Pattern
+```typescript
+async function fetchProfile(userId: string) {
+  const { data, error } = await supabase
+    .from('profiles')
+    .select('*')
+    .eq('id', userId)
+    .single()
+
+  if (error) {
+    console.error('Error fetching profile:', error)
+    throw new Error(`Failed to fetch profile: ${error.message}`)
+  }
+
+  return data
+}
+```
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Quality Gate:** [ ] PASS [ ] NEEDS REVIEW