dss/docs/ARCHITECTURE.md

# DSS Architecture

> Detailed system design, module interactions, and extension points

## System Overview

DSS follows a **layered architecture** with clear separation of concerns:

```
Clients (Admin UI, CLI, AI Agents)
           ↓
    API Layer (REST + MCP)
           ↓
    Core Modules (Ingest, Analyze, Storybook, Figma)
           ↓
    Data Layer (SQLite, File Cache)
```

## Architecture Principles

1. **Separation of Concerns**: Each module has a single, well-defined responsibility
2. **Dependency Inversion**: Modules depend on abstractions (base classes), not concrete implementations
3. **Open/Closed**: Open for extension (new parsers), closed for modification (core unchanged)
4. **Immutability**: DSS canonical structure is immutable; external systems adapt via translation
5. **Local-First**: All operations are local by default; remote access requires explicit configuration

## Module Interactions

### Data Flow: Figma → DSS → Storybook

```
┌──────────┐
│  Figma   │
│   API    │
└────┬─────┘
     │ 1. Extract variables/components
     ▼
┌──────────────┐
│ figma_tools  │ ──┐
└──────────────┘   │
                   │ 2. Parse to DesignToken
                   ▼
              ┌─────────────┐
              │   ingest    │
              │   base.py   │
              └──────┬──────┘
                     │ 3. Store tokens
                     ▼
              ┌─────────────┐
              │   storage   │
              │ database.py │
              └──────┬──────┘
                     │ 4. Load tokens
                     ▼
              ┌─────────────┐
              │  storybook  │
              │  theme.py   │
              └──────┬──────┘
                     │ 5. Generate theme
                     ▼
              ┌─────────────┐
              │  Storybook  │
              │  theme.js   │
              └─────────────┘
```

### Data Flow: Code Analysis → Quick Wins

```
┌──────────────┐
│ React Project│
└──────┬───────┘
       │ 1. Scan files
       ▼
┌──────────────┐
│   analyze    │
│  scanner.py  │
└──────┬───────┘
       │ 2. Extract components
       ▼
┌──────────────┐
│   analyze    │
│  react.py    │
└──────┬───────┘
       │ 3. Analyze styles
       ▼
┌──────────────┐
│   analyze    │
│  styles.py   │
└──────┬───────┘
       │ 4. Find issues
       ▼
┌──────────────┐
│   analyze    │
│quick_wins.py │
└──────┬───────┘
       │ 5. Generate report
       ▼
┌──────────────┐
│   MCP Tool   │
│ get_quick_wins│
└──────────────┘
```

## Module Design

### 1. Ingestion Module (`/tools/ingest/`)

**Responsibility**: Parse design tokens from multiple sources

**Class Hierarchy**:
```
TokenSource (ABC)
├── CSSTokenSource
├── SCSSTokenSource
├── TailwindTokenSource
├── JSONTokenSource
└── FigmaTokenSource
```

**Key Methods**:
- `parse()` - Extract tokens from source
- `normalize()` - Convert to DSS canonical format
- `validate()` - Check token validity

**Extension Point**: Add new `TokenSource` subclass for new formats

**Example**:
```python
from tools.ingest.base import TokenSource, DesignToken

class YAMLTokenSource(TokenSource):
    def parse(self, content: str) -> List[DesignToken]:
        # Parse YAML
        # Return DesignToken list
        pass
```

### 2. Analysis Module (`/tools/analyze/`)

**Responsibility**: Code intelligence and improvement detection

**Class Hierarchy**:
```
ProjectScanner
├── detect_framework()
├── detect_styling()
└── scan_files()

ReactAnalyzer
├── extract_components()
├── find_inline_styles()
└── analyze_imports()

StyleAnalyzer
├── find_duplicates()
├── find_token_candidates()
└── analyze_naming()

DependencyGraph
├── build()
├── find_orphans()
└── find_hubs()

QuickWinFinder
├── find_all()
├── prioritize()
└── generate_report()
```

**Extension Point**: Add new analyzer for Vue, Angular, etc.

**Example**:
```python
from tools.analyze.base import ProjectAnalyzer

class VueAnalyzer(ProjectAnalyzer):
    def analyze(self, path: str) -> ProjectAnalysis:
        # Analyze Vue files
        pass
```

### 3. Storybook Module (`/tools/storybook/`)

**Responsibility**: Storybook integration and generation

**Class Hierarchy**:
```
StorybookScanner
├── find_stories()
├── parse_story()
└── get_coverage()

StoryGenerator
├── generate_story()
├── select_template()
└── render()

ThemeGenerator
├── generate_from_tokens()
├── generate_theme_file()
└── generate_preview_head()
```

**Templates**:
- CSF3: Modern Component Story Format
- CSF2: Legacy format
- MDX: Markdown + JSX

**Extension Point**: Add new template types

### 4. Figma Module (`/tools/figma/`)

**Responsibility**: Figma API integration

**Class Hierarchy**:
```
FigmaClient
├── get_file()
├── get_variables()
├── get_components()
└── get_styles()

FigmaToolSuite
├── extract_variables()
├── extract_components()
├── extract_styles()
├── sync_tokens()
└── validate_components()
```

**Caching Strategy**:
- SQLite-based cache
- Configurable TTL (default 300s)
- Cache key: `figma:{md5(endpoint)}`

**Fallback Strategy**:
1. Try Variables API (requires paid plan)
2. Fall back to document-level data (free)

### 5. Storage Module (`/tools/storage/`)

**Responsibility**: Data persistence

**Tables**:
```sql
CREATE TABLE cache (
    key TEXT PRIMARY KEY,
    value TEXT,
    expires_at INTEGER
);

CREATE TABLE activity_log (
    id INTEGER PRIMARY KEY,
    timestamp INTEGER,
    action TEXT,
    entity_type TEXT,
    entity_id TEXT,
    details TEXT
);
```

**Extension Point**: Add new tables for migration tracking, etc.

## API Design

### REST API Pattern

```python
@app.get("/tokens")
async def list_tokens(
    category: Optional[str] = None,
    source: Optional[str] = None
):
    """List all tokens with optional filters"""
    # Implementation
    pass
```

### MCP Tool Pattern

```python
@mcp.tool()
async def analyze_react_components(path: str) -> str:
    """
    Analyze React components in project.

    Args:
        path: Path to React project

    Returns:
        JSON with component analysis
    """
    # Implementation
    pass
```

## Configuration Management

### Environment Variables

```python
# tools/config.py

class FigmaConfig:
    token: str = os.getenv("FIGMA_TOKEN", "")
    cache_ttl: int = int(os.getenv("FIGMA_CACHE_TTL", "300"))
    use_variables_api: bool = bool(token)

class ServerConfig:
    host: str = os.getenv("DSS_MCP_HOST", "127.0.0.1")
    port: int = int(os.getenv("DSS_MCP_PORT", "3457"))
    rest_port: int = int(os.getenv("PORT", "3456"))
```

### Security

- **No external MCP connections** by default
- **Local-only operations** unless explicitly configured
- **Environment-based secrets** (never hardcoded)
- **Host/port configuration** for remote access

## Extension Points

### 1. Add New Token Source

```python
# tools/ingest/new_source.py
from tools.ingest.base import TokenSource

class NewTokenSource(TokenSource):
    def parse(self, content: str) -> List[DesignToken]:
        # Parse implementation
        pass
```

### 2. Add New Analyzer

```python
# tools/analyze/vue.py
from tools.analyze.base import ProjectAnalyzer

class VueAnalyzer(ProjectAnalyzer):
    def analyze(self, path: str) -> ProjectAnalysis:
        # Vue-specific analysis
        pass
```

### 3. Add New MCP Tool

```python
# tools/api/mcp_server.py
@mcp.tool()
async def new_tool(param: str) -> str:
    """Tool description"""
    # Implementation
    pass
```

### 4. Add New REST Endpoint

```python
# tools/api/server.py
@app.get("/new-endpoint")
async def new_endpoint():
    """Endpoint description"""
    # Implementation
    pass
```

## Error Handling Strategy

### Python Modules

```python
try:
    result = await operation()
except FigmaAPIError as e:
    logger.error(f"Figma API error: {e}")
    return {"error": str(e), "status": "failed"}
except ValidationError as e:
    logger.error(f"Validation error: {e}")
    return {"error": str(e), "status": "invalid"}
except Exception as e:
    logger.error(f"Unexpected error: {e}")
    return {"error": "Internal error", "status": "error"}
```

### MCP Tools

- Return JSON strings with `{"error": "message"}` on failure
- Use descriptive error messages
- Log errors for debugging

### REST API

- Use proper HTTP status codes (400, 404, 500)
- Return consistent error format
- Include error details in response body

## Performance Considerations

### Caching

- **Figma API**: SQLite cache with TTL
- **File scanning**: Cache project structure
- **Token parsing**: Cache parsed results

### Optimization Targets

- Project analysis: < 5 seconds for 100-component project
- Token merge: < 1 second for 1000 tokens
- Figma extraction: < 3 seconds (with cache)

### Scaling Limits

- **Tokens**: Tested up to 1000 tokens
- **Components**: Tested up to 100 components
- **Files**: Tested up to 500 files

## Testing Strategy

### Unit Tests

```bash
pytest tools/ingest/  # Test parsers
pytest tools/analyze/ # Test analyzers
pytest tools/storybook/ # Test generators
```

### Integration Tests

```bash
pytest tests/integration/  # End-to-end workflows
```

### Test Coverage Goals

- Core modules: > 80%
- Utils: > 60%
- Overall: > 70%

## Deployment Architecture

### Development

```
Local Machine
├── Python 3.x
├── Node.js (for CLI)
└── SQLite database
```

### Production

```
Server (overbits user)
├── systemd services
│   ├── dss-api.service (REST API)
│   └── dss-mcp.service (MCP server)
├── nginx reverse proxy
├── SSL/TLS (Let's Encrypt)
└── SQLite database
```

## Future Architecture Considerations

### Phase 4: Migration Engine

```
Migration Module
├── AST Parser (tree-sitter)
├── Code Transformer
├── Preview Generator
├── Rollback System
└── Test Generator
```

### Phase 5: UI Library Compatibility

```
Compatibility Module
├── HeroUI Translator
├── shadcn Translator
├── Tailwind v4 Generator
└── Translation Dictionary Generator
```

## Monitoring & Logging

### Activity Log

All major operations logged to SQLite:
- Token ingestion
- Figma API calls
- Analysis runs
- Storybook generation

### Metrics

- Cache hit rate
- API response times
- Error frequencies
- Tool usage statistics

## Security Architecture

### Threat Model

1. **Token Exposure**: Figma tokens in environment variables
2. **Injection Attacks**: CSS/SCSS parsing vulnerabilities
3. **Path Traversal**: File system access attacks

### Mitigations

1. **Environment-based secrets**: No hardcoded tokens
2. **Input validation**: Sanitize all user inputs
3. **Path restrictions**: Validate file paths before access
4. **Sandboxing**: Run parsers in isolated contexts

## Maintenance

### Regular Tasks

- Clear old cache entries (> 7 days)
- Archive old activity logs (> 30 days)
- Update dependencies (monthly)
- Review error logs (weekly)

### Health Checks

```bash
# Check MCP server
curl http://localhost:3457/health

# Check REST API
curl http://localhost:3456/status

# Check database
sqlite3 .dss/dss.db "SELECT COUNT(*) FROM cache;"
```

## Documentation Maintenance

- Update PROJECT_MEMORY.md after major changes
- Update this file when architecture changes
- Keep DSS_PRINCIPLES.md synchronized with implementation
- Document all breaking changes in CHANGELOG.md