dss/docs/architecture/OVERVIEW.md

# DSS Architecture Overview

> **The 7-layer architecture for the Design System Swarm**

---

## System Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                    LAYER 7: INTEGRATION                         │
│                 APIs, MCP Tools, Webhooks, CLI                  │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 6: PRESENTATION                        │
│               Admin UI, Storybook, Documentation                │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 5: PROCESSING                          │
│           Transformations, Analysis, Style-Dictionary           │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 4: STATE                               │
│              Token Models, Stores, Data Flow                    │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 3: VALIDATION                          │
│             Schema Checking, Linting, Error Detection           │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 2: INGESTION                           │
│         File Parsing, Token Extraction (CSS, Figma, JSON)       │
├─────────────────────────────────────────────────────────────────┤
│                    LAYER 1: CORE                                │
│          Configuration, Schemas, Database, Event Bus            │
└─────────────────────────────────────────────────────────────────┘
```

---

## Layer Details

### Layer 1: Core

**Purpose**: Foundation services and persistent storage.

| Module | Responsibility |
|--------|----------------|
| `storage/` | SQLite database, migrations |
| `settings.py` | Configuration management |
| `schemas/` | JSON schemas for validation |
| `events/` | Event bus for layer communication |

**Key Patterns**:
- Single source of truth (database)
- Immutable core schemas
- Event-driven communication

**Health Indicators**:
- Database connectivity
- Schema validity
- Event bus latency

---

### Layer 2: Ingestion

**Purpose**: Extract tokens from external sources.

| Module | Source Type |
|--------|-------------|
| `ingest/css.py` | CSS custom properties |
| `ingest/scss.py` | SCSS variables |
| `ingest/figma.py` | Figma API |
| `ingest/json.py` | JSON token files |
| `ingest/tailwind.py` | Tailwind config |

**Key Patterns**:
- Translation dictionaries
- Normalized token format
- Zero data loss parsing

**Health Indicators**:
- Parse success rate
- Source availability
- Extraction completeness

---

### Layer 3: Validation

**Purpose**: Ensure token quality and consistency.

| Module | Validation Type |
|--------|-----------------|
| `validators/schema.py` | JSON schema compliance |
| `validators/naming.py` | Naming convention rules |
| `validators/contrast.py` | Color accessibility |
| `validators/completeness.py` | Token coverage |

**Key Patterns**:
- Fail-fast validation
- Actionable error messages
- Warning vs error distinction

**Health Indicators**:
- Error count
- Warning count
- Validation pass rate

---

### Layer 4: State

**Purpose**: Token data models and state management.

| Module | Responsibility |
|--------|----------------|
| `models/token.py` | Token data class |
| `models/collection.py` | Token collection |
| `models/theme.py` | Theme configuration |
| `stores/` | State containers |

**Key Patterns**:
- Immutable data classes
- Observable state
- Computed derivations

**Health Indicators**:
- Token count
- Coverage score
- Consistency score

---

### Layer 5: Processing

**Purpose**: Transform and analyze tokens.

| Module | Responsibility |
|--------|----------------|
| `tools/transform.py` | Format conversion |
| `tools/generate.py` | Output generation |
| `analyze/patterns.py` | Pattern detection |
| `analyze/audit.py` | Component auditing |

**Key Patterns**:
- Style-dictionary integration
- Multi-format output
- Analysis reports

**Health Indicators**:
- Transform success rate
- Output validity
- Analysis coverage

---

### Layer 6: Presentation

**Purpose**: User interfaces and documentation.

| Module | Responsibility |
|--------|----------------|
| `admin-ui/` | Web administration interface |
| `storybook/` | Component documentation |
| `docs/` | Written documentation |

**Key Patterns**:
- Web components
- Keyboard accessibility
- Living documentation

**Health Indicators**:
- Component coverage
- Story completeness
- Documentation freshness

---

### Layer 7: Integration

**Purpose**: External system connectivity.

| Module | Responsibility |
|--------|----------------|
| `api/rest.py` | REST API endpoints |
| `api/mcp.py` | MCP tool server |
| `api/webhooks.py` | Webhook handlers |
| `cli/` | Command-line interface |

**Key Patterns**:
- RESTful design
- MCP protocol compliance
- Event-driven webhooks

**Health Indicators**:
- API latency
- MCP tool availability
- Webhook delivery rate

---

## Data Flow

### Token Ingestion Flow

```
External Source (Figma/CSS/JSON)
         │
         ▼
    ┌─────────┐
    │ Layer 2 │  Ingestion: Parse and extract
    │Ingestion│
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ Layer 3 │  Validation: Check quality
    │Validate │
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ Layer 4 │  State: Store in models
    │  State  │
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ Layer 1 │  Core: Persist to database
    │  Core   │
    └─────────┘
```

### Token Output Flow

```
    ┌─────────┐
    │ Layer 1 │  Core: Read from database
    │  Core   │
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ Layer 4 │  State: Load into models
    │  State  │
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ Layer 5 │  Processing: Transform format
    │ Process │
    └────┬────┘
         │
         ├─────────────────┬─────────────────┐
         ▼                 ▼                 ▼
    ┌─────────┐       ┌─────────┐       ┌─────────┐
    │ Layer 6 │       │ Layer 7 │       │  File   │
    │   UI    │       │   API   │       │ Output  │
    └─────────┘       └─────────┘       └─────────┘
```

---

## Module Directory Structure

```
dss-mvp1/
├── storage/           # Layer 1: Core
│   ├── database.py
│   ├── migrations/
│   └── schemas/
├── ingest/            # Layer 2: Ingestion
│   ├── css.py
│   ├── scss.py
│   ├── figma.py
│   ├── json.py
│   └── tailwind.py
├── validators/        # Layer 3: Validation
│   ├── schema.py
│   ├── naming.py
│   └── contrast.py
├── models/            # Layer 4: State
│   ├── token.py
│   ├── collection.py
│   └── theme.py
├── tools/             # Layer 5: Processing
│   ├── transform.py
│   ├── generate.py
│   └── analyze/
├── admin-ui/          # Layer 6: Presentation
│   ├── js/
│   ├── css/
│   └── index.html
├── storybook/         # Layer 6: Presentation
│   └── stories/
├── api/               # Layer 7: Integration
│   ├── rest.py
│   └── mcp.py
└── cli/               # Layer 7: Integration
    └── main.py
```

---

## Cross-Cutting Concerns

### Logging

All layers log to a unified system:
```python
from dss.core.logging import get_logger
logger = get_logger(__name__)
```

### Error Handling

Errors propagate with context:
```python
class DSSError(Exception):
    """Base error with layer context"""
    layer: str
    details: dict
```

### Configuration

Environment-based configuration:
```python
from dss.core.settings import settings
db_path = settings.database_path
```

---

## Layer Communication

### Event Bus

Layers communicate via events:
```python
# Layer 2 emits
events.emit('tokens.ingested', collection)

# Layer 3 listens
@events.on('tokens.ingested')
def validate_tokens(collection):
    ...
```

### Direct Calls

Lower layers called by higher:
```python
# Layer 5 calls Layer 4
from dss.models import TokenCollection
tokens = TokenCollection.load()
```

### Rules

1. **Downward only** - Higher layers call lower
2. **Events for upward** - Use events for notifications
3. **No skipping** - Each layer uses adjacent layer
4. **Interface contracts** - Clear APIs between layers

---

## See Also

- [First Principles](../principles/FIRST_PRINCIPLES.md) - Foundational truths
- [Atomic Hierarchy](../principles/ATOMIC_HIERARCHY.md) - 5-level composition
- [Glossary](../GLOSSARY.md) - Corporate terminology