# System Architecture

**Version:** 2.2.3
**Last Updated:** 2026-02-07
**Architecture Type:** Multi-layer search + generation engine

---

## 1. Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                          │
│  (User Interfaces: Claude Code, Cursor, Windsurf, CLI, etc.)   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                  ORCHESTRATION LAYER                            │
│  (CLI Installer + Skill Activation Framework)                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ uipro-cli (TypeScript)                                  │   │
│  │ - Platform detection (Claude, Cursor, Windsurf, etc.)   │   │
│  │ - Template rendering (17 platform configs)             │   │
│  │ - File generation (.claude/, .cursor/, .windsurf/)     │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                   PROCESSING LAYER                              │
│  (Python Search Engine + Design System Generator)              │
│  ┌──────────────────┐  ┌──────────────────────────────────┐   │
│  │ search.py        │  │ design_system.py                 │   │
│  │ (CLI entry)      │  │ (Design system reasoning)        │   │
│  └────────┬─────────┘  └────────┬─────────────────────────┘   │
│           │                     │                              │
│           └─────┬───────────────┘                              │
│                 │                                              │
│           ┌─────▼───────────────┐                              │
│           │ core.py             │                              │
│           │ - BM25 search       │                              │
│           │ - Domain detection  │                              │
│           │ - Result ranking    │                              │
│           └─────┬───────────────┘                              │
└────────────────┼──────────────────────────────────────────────┘
                 │
┌────────────────▼──────────────────────────────────────────────┐
│                    DATA LAYER                                 │
│  (CSV-based Knowledge Base)                                   │
│  ┌────────────────────────────────────────────────────────┐   │
│  │ Core Databases (12)                                    │   │
│  │ ┌──────────┬──────────┬────────────┬─────────────┐    │   │
│  │ │ styles   │ colors   │ typography │ products    │    │   │
│  │ │ (67)     │ (96)     │ (57)       │ (100+)      │    │   │
│  │ └──────────┴──────────┴────────────┴─────────────┘    │   │
│  │ ┌──────────┬──────────┬────────────┬─────────────┐    │   │
│  │ │ landing  │ charts   │ ux-guide   │ ui-reasoning│   │   │
│  │ │ (24)     │ (25)     │ (99)       │ (100)       │    │   │
│  │ └──────────┴──────────┴────────────┴─────────────┘    │   │
│  ├────────────────────────────────────────────────────────┤   │
│  │ Stack-Specific Guidelines (13)                         │   │
│  │ React, Next.js, Vue, Nuxt, Svelte, SwiftUI, etc.      │   │
│  └────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────┘
```

---

## 2. Layer Responsibilities

### 2.1 Data Layer

**Responsibility:** Store and provide access to design knowledge

**Components:**
- 12 core CSV databases
- 13 stack-specific CSV databases
- Metadata files (categories, relationships)

**Characteristics:**
- **Immutable at runtime** (no updates via API)
- **Versioned in git** (changes tracked)
- **Replicated** (source in src/, copy in cli/assets/)
- **Format:** UTF-8 CSV, comma-separated

**Data Flow Out:**
```
CSV files → DictReader → Python lists → BM25 ranking
```

**Design Principles:**
- Single source of truth: `src/ui-ux-pro-max/data/`
- Zero external dependencies (no database, no API)
- Offline-first (works without internet)

### 2.2 Search & Processing Layer

**Responsibility:** Query data and generate intelligent recommendations

**Components:**
- **core.py** - BM25 search algorithm
- **design_system.py** - Reasoning engine
- **search.py** - CLI entry point

**Execution Model:**
```
Input (query) → Auto-detect domain → BM25 search → Results
Input (query) → Multi-domain search → Reasoning rules → Design system
```

**Key Algorithms:**

#### BM25 Ranking
```
score(doc, query) = Σ IDF(term) * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * |doc| / avgdl))

Parameters:
- k1 = 1.5 (term frequency saturation)
- b = 0.75 (document length normalization)
- IDF = log((N - df + 0.5) / (df + 0.5) + 1)

Why BM25:
- Proven ranking algorithm for text search
- Fast (linear time complexity O(n))
- Requires no external dependencies
- Works well for short documents (CSV rows)
```

#### Domain Detection
```
query = "glassmorphism and minimalism"

Domain scores:
  style: 2 (matches "glassmorphism", "minimalism")
  product: 0
  color: 0
  landing: 0

Best domain: style (highest score)
```

#### Multi-Domain Search
```
User query: "beauty spa wellness"

Parallel searches (5 domains):
1. products.csv → "Beauty/Spa" (1 result)
   ↓ Extract UI_Category
2. ui-reasoning.csv → Match rules for Beauty/Spa
3. styles.csv → Search "beauty spa" (3 results)
4. colors.csv → Search "beauty" (2 results)
5. landing.csv → Search "spa" (2 results)
6. typography.csv → Search "elegant" (2 results)

Combine results → Apply reasoning → Output design system
```

**Characteristics:**
- **Stateless** - No memory between requests
- **Deterministic** - Same query = same results
- **Fast** - <2 seconds for design system generation
- **Portable** - Pure Python, no external deps

### 2.3 Orchestration Layer

**Responsibility:** Install skill, activate for AI assistants, manage configuration

**Components:**
- **uipro-cli** (TypeScript/Node.js)
- **Template system** (17 platform-specific configs)
- **Platform detection** (OS, AI assistant, file structure)

**Installation Flow:**
```
User: npm install -g uipro-cli && uipro init --ai claude

┌─────────────────────────────────┐
│ 1. Detect Platform              │
│ - OS (Windows/Mac/Linux)        │
│ - Project structure             │
│ - Existing .claude/ directory   │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│ 2. Load Template                │
│ - skill-content.md (base)       │
│ - claude.json (config)          │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│ 3. Render Template              │
│ - Substitute variables          │
│ - Format for platform           │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│ 4. Generate Files               │
│ - .claude/skills/...            │
│ - Copy data & scripts           │
│ - Create config files           │
└──────────────┬──────────────────┘
               │
┌──────────────▼──────────────────┐
│ 5. Activate & Verify            │
│ - Test execution                │
│ - Provide instructions          │
└─────────────────────────────────┘
```

**Key Features:**
- **Platform-agnostic** - Works for 15 different AI assistants
- **Template-based** - Easy to add new platforms
- **Offline-capable** - Bundled assets (no GitHub download needed with `--offline`)
- **Backward-compatible** - New platforms don't affect existing installations

### 2.4 Presentation Layer

**Responsibility:** Deliver results to users in appropriate format

**User Interfaces:**

| Interface | Format | Activation |
|-----------|--------|-----------|
| **Claude Code** | Markdown in chat | Auto-skill activation |
| **Cursor** | Same as Claude | Auto-skill activation |
| **Windsurf** | Same as Claude | Auto-skill activation |
| **GitHub Copilot** | Markdown output | Slash command `/ui-ux-pro-max` |
| **Kiro** | Markdown output | Slash command `/ui-ux-pro-max` |
| **CLI Direct** | ASCII/Markdown | `python search.py "query"` |
| **Design System** | ASCII/Markdown | `python search.py "query" --design-system` |

**Output Formats:**

```
ASCII (Terminal-friendly):
+────────────────────────────────────┐
│ TARGET: Serenity Spa               │
│ RECOMMENDED DESIGN SYSTEM          │
│ PATTERN: Hero-Centric + Social ... │
│ STYLE: Soft UI Evolution           │
│ COLORS:                            │
│   Primary: #E8B4B8                 │
│   Secondary: #A8D5BA               │
└────────────────────────────────────┘

Markdown (AI-friendly):
## Design System: Serenity Spa
### Pattern
Hero-Centric + Social Proof
### Style
Soft UI Evolution
...
```

---

## 3. Data Flow Architecture

### 3.1 Complete User Journey

```
┌──────────────────────────────────────────────────┐
│ User Action                                      │
│ "Build a landing page for my beauty spa"        │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ Claude Code (Skill activation)                   │
│ - Activates UI/UX Pro Max skill                  │
│ - Routes to search.py                            │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ search.py (CLI entry point)                      │
│ - Parse arguments: "beauty spa" --design-system  │
│ - Call design_system.generate_design_system()    │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ design_system.py (Multi-domain search)           │
│ 1. Multi-domain search (5 parallel):             │
│    - products.csv → "Beauty/Spa"                 │
│    - styles.csv → ["Soft UI", "Claymorphism"]   │
│    - colors.csv → [soft palette #1, #2]         │
│    - landing.csv → ["Hero + Social Proof"]      │
│    - typography.csv → ["Cormorant + Montserrat"]│
│                                                  │
│ 2. Find reasoning rule → "Wellness/Beauty"      │
│    - Recommended pattern                         │
│    - Style priorities                            │
│    - Color mood                                  │
│    - Anti-patterns                               │
│                                                  │
│ 3. Apply reasoning rules to results              │
│    - Filter conflicting styles                   │
│    - Weight by industry relevance                │
│    - Generate complete design system             │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ core.py (BM25 search engine)                     │
│ - For each search domain:                        │
│   1. Load CSV                                    │
│   2. Build BM25 index                            │
│   3. Score query against documents              │
│   4. Return top K results                        │
└──────────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ Output Generation                                │
│ - Format as ASCII/Markdown                       │
│ - Include pre-delivery checklist                 │
│ - Return to Claude Code                          │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────┐
│ Claude generates HTML/React with design system   │
│ - Applies colors, typography, effects           │
│ - Follows pattern structure                      │
│ - Respects anti-patterns                         │
│ - Passes pre-delivery checklist                  │
└──────────────────────────────────────────────────┘
```

### 3.2 CLI Installation Flow

```
npm install -g uipro-cli
         │
         ▼
uipro init --ai claude
         │
         ▼
┌──────────────────────────────────────────────────┐
│ Detect Platform (detect.ts)                      │
│ - Check environment variables                    │
│ - Check file system (.claude/, .cursor/, etc.)   │
│ - Detect OS (Windows/Mac/Linux)                  │
└──────────────┬───────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│ Load Templates (template.ts)                     │
│ - Load skill-content.md (base)                   │
│ - Load claude.json (config)                      │
│ - Load 25 CSV files from assets/data/            │
│ - Load 3 Python scripts from assets/scripts/     │
└──────────────┬───────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│ Render Templates                                 │
│ - Substitute ${SKILL_PATH}, ${AI_NAME}, etc.     │
│ - Format for platform conventions                │
└──────────────┬───────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│ Generate Files                                   │
│ - Create .claude/skills/ui-ux-pro-max/           │
│ - Generate SKILL.md                              │
│ - Copy data/ & scripts/                          │
│ - Write .claude-plugin/plugin.json               │
└──────────────┬───────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────┐
│ Verify & Activate                                │
│ - Test Python environment                        │
│ - Run first test search                          │
│ - Display activation instructions                │
└──────────────────────────────────────────────────┘
```

---

## 4. Component Interactions

### 4.1 Search Engine Components

```
Query String
    │
    ▼
┌─────────────────────┐
│ detect_domain()     │ (core.py)
│ Auto-detect domain  │
│ from keywords       │
└────────┬────────────┘
         │
         ▼
┌──────────────────────────────────────────┐
│ search(query, domain)                     │ (core.py)
│ 1. Load CSV (data_dir/domain.csv)        │
│ 2. Call _search_csv()                    │
└────────┬─────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────┐
│ _search_csv()                             │ (core.py)
│ 1. Extract search columns from CSV       │
│ 2. Build BM25 index                      │
│ 3. Score query against all documents    │
└────────┬─────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────┐
│ BM25.score(query)                         │ (core.py)
│ 1. Tokenize query                         │
│ 2. For each document:                     │
│    - Calculate TF for each token          │
│    - Look up IDF for each token           │
│    - Sum BM25 scores                      │
│ 3. Return ranked list [(idx, score), ...] │
└────────┬─────────────────────────────────┘
         │
         ▼
Results (top K with output columns)
```

### 4.2 Design System Generator Components

```
Query String
    │
    ▼
┌──────────────────────────────────────────────────┐
│ generate_design_system(query, project_name)      │ (design_system.py)
│ 1. Initialize DesignSystemGenerator              │
│ 2. Call _multi_domain_search()                   │
│ 3. Call _find_reasoning_rule()                   │
│ 4. Call _apply_reasoning()                       │
│ 5. Format output (ASCII or Markdown)             │
│ 6. Persist to disk (optional)                    │
└───┬──────────────────────────────────────────────┘
    │
    ├─────────────────────┬─────────────────────┐
    │                     │                     │
    ▼                     ▼                     ▼
┌──────────┐    ┌──────────────┐    ┌──────────────┐
│ Search   │    │ Find Rule    │    │ Apply        │
│ Products │    │ by Category  │    │ Reasoning    │
│ (1 res)  │    │ → UI_Reasoning│    │ & Generate  │
│          │    │ .csv match   │    │ Output      │
└──────────┘    └──────────────┘    └──────────────┘
    │                     │                     │
    └─────────────────────┴─────────────────────┘
                          │
                          ▼
                ┌──────────────────┐
                │ Parallel Search  │
                │ - Styles (3)     │
                │ - Colors (2)     │
                │ - Landing (2)    │
                │ - Typography (2) │
                └────────┬─────────┘
                         │
                         ▼
              Design System Output
              + Pre-delivery checklist
```

---

## 5. Database Schema

### 5.1 Core Database Relationships

```
products.csv
├─ Product Type (e.g., "Beauty/Spa")
├─ Primary Style Recommendation (→ ui-reasoning.csv)
├─ Secondary Styles (→ styles.csv)
├─ Landing Page Pattern (→ landing.csv)
├─ Color Palette Focus (→ colors.csv)
└─ Dashboard Style (optional)
        │
        ▼
ui-reasoning.csv
├─ UI_Category = Product Type
├─ Recommended Pattern (→ landing.csv)
├─ Style Priority (→ styles.csv)
├─ Color Mood (→ colors.csv)
├─ Typography Mood (→ typography.csv)
├─ Anti-patterns (text)
└─ Decision Rules (JSON conditions)
        │
        ├─────────────┬─────────────┬─────────────┐
        ▼             ▼             ▼             ▼
    styles.csv   colors.csv   typography.csv  landing.csv
    (67 rows)    (96 rows)    (57 rows)       (24 rows)
```

### 5.2 Search Column Mapping

| CSV File | Search Columns | Indexed For | Purpose |
|----------|-----------------|------------|---------|
| styles.csv | Style Category, Keywords, Best For, Type, AI Prompt Keywords | Full-text BM25 | Find matching styles |
| colors.csv | Product Type, Notes | BM25 | Find industry color palettes |
| typography.csv | Font Pairing Name, Category, Mood Keywords, Best For, Heading/Body Font | BM25 | Find font pairings |
| landing.csv | Pattern Name, Keywords, Conversion Optimization, Section Order | BM25 | Find page patterns |
| products.csv | Product Type, Keywords, Primary Style, Key Considerations | BM25 | Identify product category |

---

## 6. Caching & Optimization

### 6.1 Current State (No Caching)

**Characteristics:**
- CSV loaded fresh on each query
- BM25 index built each time
- No in-memory caching

**Performance Impact:**
- First query: ~1.5-2s (includes CSV load + indexing)
- Repeated queries: Same time (no cache benefit)

### 6.2 Future Optimization (v2.3+)

**Proposed Caching Strategy:**
```
Cache Layer (Memory):
├─ Loaded CSVs (25 files, ~5MB)
├─ BM25 indexes (per domain)
├─ Last 10 queries + results
└─ TTL: 1 hour (user session)

Trigger: First search per session
Benefit: 2nd+ queries → ~200ms (skip CSV load)
```

---

## 7. Scalability Considerations

### 7.1 Current Limits

| Constraint | Current | Limit | Reached? |
|-----------|---------|-------|----------|
| CSV files | 25 | 50 | No |
| Rows per CSV | 100 | 1,000 | No |
| Total data size | 1.1MB | 10MB | No |
| Search domains | 9 | 20 | No |
| Platforms | 15 | 30 | No |

### 7.2 Scaling Strategy

**If data grows 10x:**
- Add pagination to CSV results
- Implement incremental BM25 indexing
- Move to SQLite database (optional)
- Add caching layer

**If platforms grow 2x:**
- Use platform family templates (reduces duplication)
- Parameterize platform detection
- Auto-generate platform configs

---

## 8. Error Handling & Resilience

### 8.1 Graceful Degradation

```
Scenario: CSV file missing
  → Return {"error": "File not found", "domain": "style"}
  → User sees helpful message
  → No crash

Scenario: Query matches nothing
  → Return empty results list
  → User gets message "No results found"
  → Suggest alternative search

Scenario: Python script not found
  → CLI fails with clear message
  → Suggests reinstalling uipro-cli
  → Provides troubleshooting URL
```

### 8.2 Validation Layers

```
Input Validation:
  query string → length check → tokenization → BM25 scoring

CSV Validation:
  read file → encoding check → header validation → type inference

Output Validation:
  results → truncate long values → format → return
```

---

## 9. Deployment Architecture

### 9.1 Distribution Channels

```
Source of Truth: src/ui-ux-pro-max/
         │
         ├─ Symlink → .shared/ui-ux-pro-max/
         ├─ Symlink → .claude/skills/ui-ux-pro-max/
         │
         └─ Copy → cli/assets/
                │
                └─ npm publish uipro-cli
                        │
                        └─ Users: npm install -g uipro-cli
                              │
                              └─ uipro init --ai claude
                                    │
                                    └─ Generates .claude/skills/
```

### 9.2 Version Synchronization

**Current Issues:**
- CLI: v2.2.3
- Marketplace: v2.2.1
- Plugin: v2.0.1 (outdated)

**Solution:**
1. Update plugin.json → v2.2.3
2. Update marketplace.json → v2.2.3
3. Tag release: v2.2.3
4. Sync CLI assets before publish

---

## 10. Security Architecture

### 10.1 Threat Model

| Threat | Impact | Mitigation |
|--------|--------|-----------|
| **Code injection via query** | Moderate | Tokenization & regex (no eval) |
| **CSV injection via data** | Low | Data validation on load |
| **Path traversal** | Low | Use pathlib, whitelist directories |
| **Secrets in code** | High | Pre-commit hook scanning |
| **Dependency vulnerabilities** | Moderate | npm audit, minimal deps |

### 10.2 Security Best Practices

```python
# Good: Safe path handling
from pathlib import Path
data_dir = Path(__file__).parent / "data"
filepath = data_dir / filename
if not filepath.is_relative_to(data_dir):
    raise ValueError("Path traversal detected")

# Good: Input validation
def tokenize(text):
    """Tokenize with safety checks"""
    if not isinstance(text, str):
        raise TypeError("Query must be string")
    if len(text) > 1000:
        text = text[:1000]  # Truncate
    return [w for w in text.lower().split() if len(w) > 2]

# Avoid
def search(query):
    # Code injection risk!
    exec(f"find_in_database({query})")
```

---

## 11. Monitoring & Observability

### 11.1 Metrics to Track

```
Search Engine:
- Query count (per domain)
- Average search time
- Cache hit rate (future)
- Top 10 queries

Design System Generation:
- Query count
- Average generation time
- Most popular product types
- Most selected styles

CLI Installation:
- Total installs
- Platform distribution
- Installation success rate
- Common errors
```

### 11.2 Logging Strategy

```python
# Verbose logging (enabled with --verbose)
logger.debug(f"Loading CSV: {filepath}")
logger.debug(f"BM25 index built: {len(self.corpus)} docs")
logger.debug(f"Query tokens: {query_tokens}")
logger.info(f"Search completed in {elapsed_ms}ms")

# Error logging
logger.error(f"CSV load failed: {error}")
logger.warning(f"Query returned 0 results")
```

---

## 12. Technology Stack

| Layer | Technology | Why Chosen |
|-------|-----------|-----------|
| **Search Engine** | Python 3.x (pure stdlib) | Zero dependencies, portable |
| **CLI** | TypeScript + Bun | Fast compilation, clear types |
| **Data** | CSV (UTF-8) | Simple, version-controllable |
| **Ranking** | BM25 algorithm | Proven, efficient, no ML needed |
| **Distribution** | npm + GitHub | Reach JavaScript/Node users |
| **Platforms** | 15 AI assistants | Maximum user coverage |

---

## 13. Future Architecture Considerations

### 13.1 v3.0 Vision

```
Current (v2.2):
  CSV → BM25 → Design System (rule-based)

Future (v3.0):
  CSV → Embeddings → Semantic search → LLM-enhanced → Design System
  (Better semantic understanding, LLM-powered reasoning)

Benefits:
- More natural language queries
- Semantic similarity matching
- Adaptive recommendations
- Real-time learning
```

### 13.2 Potential Enhancements

1. **Design Token Export** - Generate CSS variables from palettes
2. **Figma Integration** - Auto-create design systems in Figma
3. **Component Preview** - Real-time UI component rendering
4. **Accessibility Audit** - Auto-check contrast ratios, WCAG compliance
5. **A/B Testing** - Compare design systems, track performance
6. **Collaborative Editor** - Team-based design system refinement

---

## Unresolved Questions

1. **Semantic Search:** Should we add embedding-based search (OpenAI API) for v3.0?
2. **Real-time Analytics:** How to track design system popularity without telemetry?
3. **Caching Layer:** Memory or disk? TTL? Shared across sessions?
4. **Multi-language:** Should we support design systems in non-English languages?
5. **API Stability:** How to version Python modules for external users?