dss/docs/architecture/OVERVIEW.md

DSS Architecture Overview

The 7-layer architecture for the Design System Server

---

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:

from dss.core.logging import get_logger
logger = get_logger(__name__)

Error Handling

Errors propagate with context:

class DSSError(Exception):
    """Base error with layer context"""
    layer: str
    details: dict

Configuration

Environment-based configuration:

from dss.core.settings import settings
db_path = settings.database_path

---

Layer Communication

Event Bus

Layers communicate via events:

# 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:

# 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 - Foundational truths
• Atomic Hierarchy - 5-level composition
• Glossary - Corporate terminology