dss/docs/DOCUMENTATION_HUB.md

📚 DSS Documentation Hub: The Organism's Permanent Memory

Welcome to the DSS Documentation Hub - the central repository where all knowledge about the design system organism lives. This is where we store what we've learned, how systems work, and where to find answers.

Think of this as the organism's brain - everything the system knows is recorded here.

---

🧠 Navigation

Quick Links (Start Here)

• Getting Started - New to DSS? Start here
• Organism Framework - Understand the biology
• Extended Learning - Deep dives into each system
• How-To Guides - Common tasks and workflows
• Troubleshooting - Problem solving

---

Getting Started

For First-Time Users

1. Quick Start - 5-minute overview
2. Organism Overview - System introduction
3. Key Concepts - Important ideas

For Developers

1. Code Integration Guide - How to use organism vocabulary in code
2. Architecture - System design
3. Token Ingestion - How tokens enter the system

For Designers

1. Design System Principles - Philosophy and approach
2. Storybook Guide - Documentation and presentation
3. Quick Start Organism - Fast reference

For DevOps/Infrastructure

1. Deployment - Running the system
2. Architecture - System structure
3. Performance - Optimization and monitoring

---

Organism Framework

Foundation

• DSS Organism Guide - The complete framework
• Organism Diagram - Visual architecture
• Framework Summary - Executive overview

Vocabulary

• Quick Glossary - Quick reference (A-Z)
• Extended Glossary - Deep dive into every term
• Usage Guide - How to use in communication

The 11 Organ Systems

Each system below has detailed documentation:

1. ❤️ Heart (Database)

• What It Is: The persistent storage layer
• Key Files: dss/storage/
• Vital Signs: Response time, consistency, backup integrity
• Health Check: Run python -m dss.settings check-deps
• Read More: DSS Organism Guide - Heart

2. 🧠 Brain (Validators & Analysis)

• What It Is: Validation rules and pattern detection
• Key Files: dss/validators/, dss/analyze/
• Vital Signs: Validation accuracy, pattern detection rate
• Health Check: Run unit tests: pytest tests/unit/
• Read More: Extended Glossary - Brain

3. 🔌 Nervous System (API)

• What It Is: REST API and MCP tool integration
• Key Files: dss/api/, tools/dss_mcp/
• Vital Signs: Response latency, endpoint availability
• Health Check: curl http://localhost:3456/health
• Read More: Architecture - API Layer

4. 🍽️ Digestive System (Token Ingestion)

• What It Is: Parsing and extracting tokens from various sources
• Key Files: dss/ingest/
• Vital Signs: Parse success rate, processing time
• Health Check: Check ingestion tests: pytest tests/unit/ingest/
• Read More: Token Ingestion Guide

5. 🩸 Circulatory System (Design Tokens)

• What It Is: The tokens themselves and their distribution
• Key Files: dss/models/token.py
• Vital Signs: Token count, distribution coverage
• Health Check: Query token database
• Read More: Extended Glossary - Tokens

6. ⚡ Metabolic System (Transformations)

• What It Is: Converting tokens to different formats
• Key Files: tools/style-dictionary/, dss/tools/
• Vital Signs: Transformation speed, format completeness
• Health Check: Check transformation tests
• Read More: Extended Glossary - Metabolism

7. 🎛️ Endocrine System (Themes)

• What It Is: Theme management and adaptation
• Key Files: dss/themes/
• Vital Signs: Theme availability, application success
• Health Check: Load different themes in Storybook
• Read More: DSS Organism Guide - Themes

8. 🛡️ Immune System (Validators & QA)

• What It Is: Data validation and quality assurance
• Key Files: dss/validators/schema.py
• Vital Signs: Validation pass rate, error detection
• Health Check: Run all tests: pytest
• Read More: Extended Glossary - Immunity

9. 👁️ Sensory Organs (Figma, Assets)

• What It Is: Input systems for perceiving external designs
• Key Files: tools/figma/
• Vital Signs: API response time, cache hit rate
• Health Check: Test Figma connection
• Read More: Extended Glossary - Sensory

10. 🎨 Skin (Storybook & UI)

• What It Is: Documentation and presentation layer
• Key Files: dss/storybook/, admin-ui/
• Vital Signs: Load time, user engagement
• Health Check: Visit http://localhost:6006 (Storybook), http://localhost:5173 (Admin UI)
• Read More: Storybook Config

11. 🦴 Skeleton (Schemas & Structure)

• What It Is: Naming conventions and data schemas
• Key Files: dss/models/
• Vital Signs: Naming consistency, schema compliance
• Health Check: Check schema validation tests
• Read More: Extended Glossary - Skeleton

---

Extended Learning

Deep Dives by System

Each organ system has extended documentation available:

System	Quick Ref	Extended	Code	Tests
Heart ❤️	Glossary	Guide	dss/storage/	tests/
Brain 🧠	Glossary	Analysis	dss/validators/	tests/unit/
Nervous 🔌	Glossary	Architecture	dss/api/	Integration tests
Digestive 🍽️	Glossary	Ingestion	dss/ingest/	tests/unit/ingest/
Circulatory 🩸	Glossary	Models	dss/models/	Token tests
Metabolic ⚡	Glossary	Style Dict	tools/	Transform tests
Endocrine 🎛️	Glossary	Guide	dss/themes/	Theme tests
Immune 🛡️	Glossary	Validation	dss/validators/	All tests
Sensory 👁️	Glossary	Figma	tools/figma/	Figma tests
Skin 🎨	Glossary	Storybook	dss/storybook/	UI tests
Skeleton 🦴	Glossary	Schemas	dss/models/	Schema tests

---

How-To Guides

Common Tasks

Adding a New Token Type

1. Define the token type in dss/models/token.py
2. Add validation rules in dss/validators/schema.py
3. Create ingestion logic in dss/ingest/base.py
4. Add transformation rules in tools/style-dictionary/config.js
5. Document in Storybook

Integrating a New Source

1. Create ingestor in dss/ingest/
2. Implement TokenSource abstract class
3. Add tests in tests/unit/ingest/
4. Register in API or CLI
5. Document in TOKEN_INGESTION.md

Adding a New Validator

1. Create rule in dss/validators/schema.py
2. Add error message in admin-ui/js/core/error-handler.js
3. Add test cases in tests/unit/validators/
4. Update documentation

Debugging Issues

1. Check logs: admin-ui/js/core/logger.js output
2. Run health check: python -m dss.settings check-deps
3. Check database: Query SQLite database
4. Review error messages using organism metaphors
5. Consult Troubleshooting section below

Workflow Examples

• Token Extraction Workflow
• Component Definition Workflow
• Theme Generation Workflow
• Deployment Workflow

---

Troubleshooting

By Symptom

"The organism is sluggish" (Slow performance)

• Check database response time
• Monitor CPU/memory usage
• Review API latency
• See: Performance Guide

"The organism is confused" (Validation errors)

• Review error messages from immune system
• Check token schema compliance
• Verify naming conventions
• See: Validation Guide

"The organism can't see" (Figma connection issues)

• Verify Figma token configuration
• Check sensory organs health
• Review Figma API status
• See: Figma Integration

"The organism is sick" (Data integrity issues)

• Run validation checks
• Review recent database operations
• Check for corrupted tokens
• See: Error Handling

"The organism is deaf" (Not receiving updates)

• Check API endpoints
• Verify webhook configuration
• Review event emitters
• See: Architecture - Communication

Error Messages as Organism Communication

The organism communicates health through error messages:

• 🛡️ IMMUNE ALERT - Validation failed (data rejected)
• ❤️ CRITICAL - Heart not responding (database down)
• ⚠️ SYMPTOM - Something unusual detected (warning)
• 🧠 BRAIN ALERT - Processing error (analyzer failed)
• ⚡ METABOLISM ALERT - Overload (rate limit)

Decode these messages using the Extended Glossary.

---

Documentation Structure

docs/
├── DOCUMENTATION_HUB.md (YOU ARE HERE)
│   └── Central index and navigation
├── EXTENDED_GLOSSARY.md
│   └── Complete vocabulary reference
├── DSS_ORGANISM_GUIDE.md
│   └── Framework foundation
├── Quick References
│   ├── QUICK_START_ORGANISM.md
│   ├── DSS_BIOLOGY_GLOSSARY.md
│   └── QUICK_START_ORGANISM.md
├── System Guides
│   ├── CODE_INTEGRATION_GUIDE.md
│   ├── TOKEN_INGESTION.md
│   ├── ARCHITECTURE.md
│   └── PERFORMANCE.md
├── Concepts
│   ├── DSS_ORGANISM_DIAGRAM.md
│   ├── ORGANISM_FRAMEWORK_SUMMARY.md
│   └── DSS_ORGANISM_README.md
└── Reference
    ├── TROUBLESHOOTING.md
    ├── MIGRATION.md
    └── CODE_QUALITY.md

---

What You'll Find Here

Knowledge Categories

🧠 Conceptual

• What is the organism framework?
• How do biological metaphors help?
• What are the 11 organ systems?
• Why think biologically?

🔧 Technical

• How do I implement organism vocabulary?
• What code files handle each system?
• How do I add new validators?
• How do I integrate new sources?

📚 Reference

• Quick glossary of terms
• Extended definitions with examples
• Architecture diagrams
• Data flow documentation

🐛 Problem-Solving

• How do I debug issues?
• What does this error mean?
• Why is the system slow?
• How do I fix validation errors?

📈 Development

• How do I develop new features?
• What's the testing strategy?
• How do I deploy changes?
• What are best practices?

---

Finding What You Need

By Role

New Team Members → Start with Getting Started → Read Organism Framework → Explore specific system you work on

Frontend Developers → Focus on Sensory Organs and Skin → Read Code Integration Guide → Explore admin-ui/, dss/storybook/

Backend Developers → Study Digestive System and Heart → Read Token Ingestion → Explore dss/ingest/, dss/storage/

DevOps/Infrastructure → Focus on Heart and Architecture → Read Deployment → Monitor system health

Designers → Read Quick Start → Explore Sensory Organs → Visit Storybook Guide

By Problem Type

"I don't understand how X works" → Check Extended Glossary → Read the corresponding system guide → Look at code examples in Code Integration Guide

"I'm getting an error" → Read the error message carefully → Look up the term in Extended Glossary → Check Troubleshooting → See Error Handling

"I need to add a new feature" → Find similar existing feature → Review Architecture → Check How-To Guides → Look at test examples

"The system seems broken" → Run health check: python -m dss.settings check-deps → Check Troubleshooting → Review logs in Logger → Contact DevOps/Infrastructure

---

Keeping Documentation Fresh

Documentation Standards

• Use organism vocabulary consistently
• Include code examples
• Link to related documentation
• Keep examples up-to-date
• Update when code changes

Contributing to Docs

1. Edit relevant .md file
2. Use organism vocabulary
3. Include concrete examples
4. Test all links
5. Update index/navigation if adding new section

Documentation Review Checklist

• Uses organism vocabulary consistently
• Clear and concise explanations
• Code examples work
• Links are correct
• Follows existing structure
• Updated related docs

---

Quick Stats

Metric	Value
Documentation Files	15+
Glossary Entries	100+
Organ Systems	11
Code Files	50+
API Endpoints	34
MCP Tools	32
Test Files	20+

---

Recent Changes

Latest Updates:

• ✨ Extended Glossary created with 100+ terms
• ✨ Documentation Hub (this file) created
• ✨ Organism vocabulary added to all core systems
• ✨ Error messages updated with immune system metaphors
• ✨ Logger categories expanded with organ system guidance

Planned Documentation:

• Extended guides for each organ system
• Video tutorials
• Interactive diagrams
• Code walkthrough series

---

Contact & Support

Getting Help

• Check Extended Glossary first
• Review Troubleshooting
• Ask in team chat with organism vocabulary
• Create issue if it's a bug

Feedback

• Suggest documentation improvements
• Report broken links
• Propose new topics
• Share what worked for you

---

See Also

• 🧬 DSS Organism Guide - Full framework
• 📚 Quick Reference Glossary - Quick lookup
• 🔧 Code Integration Guide - How to use in code
• 📊 Architecture - System design
• 🐛 Troubleshooting - Problem solving

---

Last Updated: 2025-12-06 Version: 1.0.0 Status: Active & Maintained

🧬 The organism's permanent memory, always growing and learning.