dss/docs/CODE_INTEGRATION_GUIDE.md

🧬 DSS Organism Framework: Code Integration Guide

How to integrate organism vocabulary into DSS code, messages, and logging.

---

Overview

The organism framework has been integrated into critical DSS code files. This guide shows:

1. ✅ Files already updated
2. 📋 Files that should be updated next
3. 🔧 How to apply the framework to code
4. 📝 Examples and templates

---

Part 1: Files Already Updated ✅

1. JavaScript Error Handler ✅ COMPLETE

File: /admin-ui/js/core/error-handler.js

What was changed:

• Module header updated with organism context
• All error messages reframed using biological metaphors
• Error titles now include emoji indicators (🛡️, ❤️, 🧠, ⚡, 🔌, etc.)
• Error categories mapped to organ systems:
  • Figma API → Sensory System issues
  • Network → Heart/Nervous System issues
  • Timeout → Metabolism overload
  • Validation → Immune/Genetic system issues

Example transformation:

Before:

figma_403: {
  title: 'Cannot access Figma file',
  message: 'Your Figma access token doesn\'t have permission to access this file.',
  actions: [
    'Check if your Figma token is valid in Settings',
    // ...
  ],
}

After:

figma_403: {
  title: '🛡️ IMMUNE ALERT: Sensory Input Blocked',
  message: 'The DSS sensory organs cannot perceive the Figma file. Your access credentials lack permission.',
  actions: [
    'Verify your Figma authentication token in Settings (nervous system communication)',
    'Confirm you have access to this file in Figma (sensory perception)',
    // ...
  ],
}

Benefits: ✅ Users understand errors as "immune system detecting threats" ✅ Emojis make error types visually distinct ✅ Action items include biological context in parentheses ✅ Creates cohesive communication style

---

2. Python Validators ✅ COMPLETE

File: /dss-mvp1/dss/validators/schema.py

What was changed:

• Module docstring refactored with organism context
• Validation stages renamed with biological metaphors:
  • Stage 1: 🛡️ Genetic Structure Check
  • Stage 2: 🧬 DNA Completeness Check
  • Stage 3: 🩸 Nutrient Quality Check
  • Stage 4: 🧬 Tissue Integrity Check
• Method docstrings explain validation as immune system antibodies
• Error messages use biological language

Example transformation:

Before:

def _validate_structure(self, data, result):
    """Stage 2: Validate required fields and structure"""
    for field in required_fields:
        if field not in data:
            result.add_error(
                ValidationStage.STRUCTURE,
                f"Missing required field: {field}",
                field
            )

After:

def _validate_structure(self, data, result):
    """
    Stage 2: 🧬 DNA COMPLETENESS CHECK
    
    The immune system checks if the genetic blueprint has all
    essential chromosomes. Missing genes prevent organism development.
    """
    for field in required_fields:
        if field not in data:
            result.add_error(
                ValidationStage.STRUCTURE,
                f"🧬 Missing essential gene: {field} (required chromosome incomplete)",
                field
            )

Benefits: ✅ Developers understand validation as "immune system protecting health" ✅ Code comments align with organism framework ✅ Error messages are more memorable ✅ Creates teaching opportunity for new developers

---

Part 2: Files Ready for Next Update 📋

HIGH PRIORITY - User-Facing Communication

File: /admin-ui/js/core/logger.js

Status: Ready for update What to change: Log level categories and formatting Suggested changes:

// BEFORE
const logLevels = {
  DEBUG: { level: 0, color: '#888', prefix: '[DEBUG]' },
  INFO: { level: 1, color: '#2196F3', prefix: '[INFO]' },
  WARN: { level: 2, color: '#FF9800', prefix: '[WARN]' },
  ERROR: { level: 3, color: '#F44336', prefix: '[ERROR]' },
};

// AFTER
const logLevels = {
  DEBUG: { level: 0, color: '#888', prefix: '🧠 [THOUGHT]' }, // Brain thinking
  INFO: { level: 1, color: '#2196F3', prefix: '💭 [AWARENESS]' }, // Organism aware
  WARN: { level: 2, color: '#FF9800', prefix: '⚠️ [SYMPTOM]' }, // Health concern
  ERROR: { level: 3, color: '#F44336', prefix: '🛡️ [IMMUNE ALERT]' }, // Threat detected
};

---

File: /dss-mvp1/dss/settings.py

Status: Ready for update What to change: CLI command messages and output formatting Suggested changes:

# BEFORE
print("Running reset...")
print("✅ Reset complete")

# AFTER - Frame as organism actions
print("🧬 Organism undergoing regeneration...")
print("✅ Regeneration complete - organism reborn")

# Health check output
print("📊 DSS System Information:")
print("❤️ Heart rate (DB latency): 145ms")
print("🧠 Brain status (Validators): All passing")
print("🩸 Circulation (Token distribution): 84/100 components")

---

File: /tools/figma/figma_tools.py

Status: Ready for update What to change: Figma integration messages and error handling Suggested messages:

# When connecting to Figma
print("🔌 Nervous system attempting sensory connection to Figma...")

# When extracting tokens
print("🍽️ Digestive system extracting nutrient particles from design file...")

# When validation passes
print("🛡️ Immune system approved: Nutrients are safe for circulation")

# Errors
raise Exception("🔌 NERVOUS SYSTEM ERROR: Cannot establish sensory link to Figma")

---

File: /dss-mvp1/dss/ingest/base.py

Status: Ready for update What to change: Token ingestion descriptions and progress messages Suggested changes:

# BEFORE
def ingest_tokens(self, tokens):
    """Ingest and normalize tokens"""
    
# AFTER - Use organism metaphors
def ingest_tokens(self, tokens):
    """
    Feed the organism - ingest tokens as nutrients
    
    The digestive system breaks down design input and extracts nutrients
    (design tokens) that the organism can use for circulation.
    """

---

MEDIUM PRIORITY - System Documentation

File: /dss-mvp1/dss/tools/style_dictionary.py

Status: Ready for update Content type: Transformation tool documentation Why important: This is the metabolic system that converts tokens

Suggested framing:

• Tool description: "The metabolic engine - converts nutrients to usable forms"
• Process description: "Metabolism of tokens to CSS, JSON, SCSS outputs"
• Output files: "Byproducts of healthy metabolism"

---

File: /dss-mvp1/dss/storybook/generator.py

Status: Ready for update Content type: Documentation generation Why important: Storybook is the "skin" of the organism

Suggested framing:

• Generator purpose: "Refresh the skin - generate Storybook documentation"
• Story creation: "Organism educating the external world through documentation"
• Component showcase: "Display how tissues (components) work together"

---

LOW PRIORITY - Core Documentation

Files that should reference the framework:

1. /dss-mvp1/README.md - Introduce organism metaphor in MVP1 overview
2. /docs/ARCHITECTURE.md - Map architecture to organism systems
3. /docs/QUICKSTART.md - Use biological language for getting started
4. /ERROR_HANDLING.md - Frame error handling as immune system

---

Part 3: How to Apply the Framework

Pattern 1: Docstrings & Comments

When documenting code, use this pattern:

def some_function(self, data):
    """
    [Emoji] ORGANISM CONTEXT - Actual function name
    
    Biological explanation of what this does in the context of the DSS
    organism. Mention which organ system or process is involved.
    
    Args:
        data: Describe what data represents biologically
        
    Returns:
        Describe what is returned in biological terms
    """

---

Pattern 2: Error Messages

When creating error messages, follow this structure:

[Emoji] SYSTEM ALERT: [Brief biological description]

[Technical problem in biological language]

What to do:
1. [Action 1 with biological context in parentheses]
2. [Action 2 with biological context in parentheses]

Example:

raise ValidationError(
    "🛡️ IMMUNE ALERT: Pathogenic Token Detected\n"
    "Token value contains invalid characters that could infect the organism.\n"
    "What to do:\n"
    "1. Remove invalid characters from the token value (clean the nutrient)\n"
    "2. Verify the token matches our genetic patterns (naming conventions)\n"
    "3. Try ingesting the token again (feed the DSS)"
)

---

Pattern 3: Logging & Progress Messages

For progress tracking and logging, map to organism processes:

logger.info("🍽️ Digestive system beginning token extraction...")
logger.debug("🧠 Brain analyzing token patterns...")
logger.warning("⚠️ Organism experiencing metabolic stress - slow processing")
logger.error("❌ Critical immune failure - infection detected and isolated")

---

Pattern 4: Configuration & Help Text

For CLI commands and settings descriptions:

@click.command()
@click.option('--feed', is_flag=True, help='Feed the DSS with new tokens from Figma')
@click.option('--health', is_flag=True, help='Check the organism vital signs')
def dss_cli(feed, health):
    """DSS Organism Control Panel - Feed, monitor, and maintain the system"""
    if feed:
        print("🍽️ Opening intake valve...")
    if health:
        print("🏥 Running vital signs diagnostic...")

---

Part 4: Integration Checklist

Phase 2A: Error Messages & Validation ✅ IN PROGRESS

• JavaScript error-handler.js - Error messages
• Python schema.py - Validator docstrings
• logger.js - Log level categories
• settings.py - CLI messages
• All other error sources

Phase 2B: Core System Messages 📋 READY

• Figma integration messages
• Token ingestion messages
• Storybook generation messages
• Database operation messages
• Analysis & report generation

Phase 2C: Documentation 📋 READY

• Code inline comments (docstrings)
• README files with organism introduction
• Architecture documentation
• Setup guides rewritten biologically

Phase 3: Team Implementation 🎯 FUTURE

• Train developers on the framework
• Establish code review standards for organism language
• Create coding guidelines document
• Set up templates for new code

---

Part 5: Code Review Guidelines

When reviewing DSS code, check for organism framework compliance:

✅ Good Patterns

# Docstring uses biological metaphor
"""
🛡️ IMMUNE SYSTEM - Validate incoming tokens
Check if tokens are safe for circulation through the organism.
"""

# Error message includes emoji and biological context
raise ValidationError("🛡️ Pathogen detected: Invalid token format")

# Comments explain organism role
# The heart (database) stores this nutrient for circulation
db.store_token(token)

❌ Patterns to Update

# Generic docstring without organism context
"""Validate tokens"""

# Technical error message
raise ValidationError("Invalid token: expected string, got dict")

# Comments without biological meaning
# This stores the token
db.store_token(token)

---

Part 6: File Organization

As you update files, organize documentation like this:

dss-mvp1/
├── README.md
│   └── Add: "The DSS Organism" section with framework link
├── dss/
│   ├── validators/
│   │   └── schema.py ✅ UPDATED
│   ├── ingest/
│   │   └── base.py 📋 READY
│   ├── tools/
│   │   └── figma.py 📋 READY
│   └── storybook/
│       └── generator.py 📋 READY
├── docs/
│   ├── ARCHITECTURE.md 📋 READY
│   ├── DSS_ORGANISM_GUIDE.md ✅ NEW
│   └── CODE_INTEGRATION_GUIDE.md ✅ THIS FILE
└── ...

---

Part 7: Examples by File Type

Python Dataclass/Pydantic Model

from dataclasses import dataclass

@dataclass
class Token:
    """🩸 NUTRIENT - A design token flowing through the circulatory system"""
    name: str  # Genetic identifier
    value: str  # Nutrient value (color, spacing, etc.)
    category: str  # Blood type (color, spacing, shadow, etc.)

---

JavaScript Promise/Async Function

/**
 * 🧬 ORGANISM PERCEPTION - Check if the sensory organs can connect to Figma
 * 
 * @async
 * @returns {Promise<boolean>} True if sensory connection established
 */
async function checkSensoryConnection() {
  try {
    const response = await fetch('https://api.figma.com/health');
    return response.ok; // Sensory organs are alive
  } catch (error) {
    console.log('🛡️ IMMUNE ALERT: Sensory disconnection detected');
    return false;
  }
}

---

REST API Endpoint

@app.get("/health")
async def health_check():
    """
    ❤️ HEART VITALS - Check if the organism is alive
    
    Returns the DSS organism's vital signs.
    """
    return {
        "status": "healthy",
        "heart_rate": get_db_latency(),  # Database query speed
        "brain_activity": get_validator_status(),  # Analysis running
        "circulation": get_token_distribution(),  # Token usage
    }

---

Part 8: Common Questions

Q: Do I HAVE to use organism language? A: Not strictly required, but recommended for user-facing messages (errors, logs, docs). Internal implementation details can stay technical.

Q: What if the metaphor doesn't fit? A: Use both biological and technical language. The framework is a communication tool, not a cage.

Q: How do I remember the 11 organs? A: Reference QUICK_START_ORGANISM.md. The organ system table shows all 11 with their functions.

Q: Can I create new biological metaphors? A: Yes! But keep them consistent and document them in the glossary if they're new.

---

Part 9: Next Steps

1. Complete Phase 2A - Finish error/validation updates (in progress)
2. Move to Phase 2B - Update system messages in ingest, Figma, storybook
3. Phase 2C - Update documentation and READMEs
4. Train team - Share the framework, establish guidelines
5. Continuous improvement - Apply to new code as it's written

---

References

📖 Full Framework: See /docs/DSS_ORGANISM_GUIDE.md
📚 Glossary: See /docs/DSS_BIOLOGY_GLOSSARY.md
⚡ Quick Start: See /docs/QUICK_START_ORGANISM.md
🗂️ Index: See /docs/INDEX_ORGANISM_FRAMEWORK.md

---

Happy integrating! The DSS organism is ready to speak biologically. 🧬✨