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](#getting-started)** - New to DSS? Start here
- **[Organism Framework](#organism-framework)** - Understand the biology
- **[Extended Learning](#extended-learning)** - Deep dives into each system
- **[How-To Guides](#how-to-guides)** - Common tasks and workflows
- **[Troubleshooting](#troubleshooting)** - Problem solving

---

## Getting Started

### For First-Time Users
1. **[Quick Start](QUICK_START_ORGANISM.md)** - 5-minute overview
2. **[Organism Overview](DSS_ORGANISM_README.md)** - System introduction
3. **[Key Concepts](DSS_ORGANISM_GUIDE.md#key-concepts)** - Important ideas

### For Developers
1. **[Code Integration Guide](CODE_INTEGRATION_GUIDE.md)** - How to use organism vocabulary in code
2. **[Architecture](ARCHITECTURE.md)** - System design
3. **[Token Ingestion](TOKEN_INGESTION.md)** - How tokens enter the system

### For Designers
1. **[Design System Principles](../DSS_PRINCIPLES.md)** - Philosophy and approach
2. **[Storybook Guide](../STORYBOOK_CONFIG.md)** - Documentation and presentation
3. **[Quick Start Organism](QUICK_START_ORGANISM.md)** - Fast reference

### For DevOps/Infrastructure
1. **[Deployment](../DEPLOYMENT.md)** - Running the system
2. **[Architecture](ARCHITECTURE.md)** - System structure
3. **[Performance](PERFORMANCE.md)** - Optimization and monitoring

---

## Organism Framework

### Foundation
- **[DSS Organism Guide](DSS_ORGANISM_GUIDE.md)** - The complete framework
- **[Organism Diagram](DSS_ORGANISM_DIAGRAM.md)** - Visual architecture
- **[Framework Summary](ORGANISM_FRAMEWORK_SUMMARY.md)** - Executive overview

### Vocabulary
- **[Quick Glossary](DSS_BIOLOGY_GLOSSARY.md)** - Quick reference (A-Z)
- **[Extended Glossary](EXTENDED_GLOSSARY.md)** - Deep dive into every term
- **[Usage Guide](IMPLEMENTING_ORGANISM_FRAMEWORK.md)** - 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](DSS_ORGANISM_GUIDE.md#heart-database)

#### 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](EXTENDED_GLOSSARY.md#-brain-validators--analysis-engine)

#### 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](ARCHITECTURE.md)

#### 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](TOKEN_INGESTION.md)

#### 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](EXTENDED_GLOSSARY.md#-tokens-nutrients)

#### 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](EXTENDED_GLOSSARY.md#-metabolic-system-transformations)

#### 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](DSS_ORGANISM_GUIDE.md#endocrine-system)

#### 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](EXTENDED_GLOSSARY.md#health--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](EXTENDED_GLOSSARY.md#sensory--perception)

#### 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](../STORYBOOK_CONFIG.md)

#### 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_GLOSSARY.md#-skeleton-schemas--structure)

---

## Extended Learning

### Deep Dives by System

Each organ system has extended documentation available:

| System | Quick Ref | Extended | Code | Tests |
|--------|-----------|----------|------|-------|
| Heart ❤️ | [Glossary](EXTENDED_GLOSSARY.md#-heart-database-layer) | [Guide](DSS_ORGANISM_GUIDE.md#heart-database) | `dss/storage/` | `tests/` |
| Brain 🧠 | [Glossary](EXTENDED_GLOSSARY.md#-brain-validators--analysis-engine) | [Analysis](../COMPONENT_AUDIT.md) | `dss/validators/` | `tests/unit/` |
| Nervous 🔌 | [Glossary](EXTENDED_GLOSSARY.md#-nervous-system-api--webhooks) | [Architecture](ARCHITECTURE.md) | `dss/api/` | Integration tests |
| Digestive 🍽️ | [Glossary](EXTENDED_GLOSSARY.md#-digestive-system-token-ingestion) | [Ingestion](TOKEN_INGESTION.md) | `dss/ingest/` | `tests/unit/ingest/` |
| Circulatory 🩸 | [Glossary](EXTENDED_GLOSSARY.md#-tokens-nutrients) | [Models](../dss-mvp1/dss/models/) | `dss/models/` | Token tests |
| Metabolic ⚡ | [Glossary](EXTENDED_GLOSSARY.md#-metabolic-system-transformations) | [Style Dict](../tools/style-dictionary/) | `tools/` | Transform tests |
| Endocrine 🎛️ | [Glossary](EXTENDED_GLOSSARY.md#-endocrine-system--hormones) | [Guide](DSS_ORGANISM_GUIDE.md#endocrine-system) | `dss/themes/` | Theme tests |
| Immune 🛡️ | [Glossary](EXTENDED_GLOSSARY.md#health--immunity) | [Validation](CODE_INTEGRATION_GUIDE.md#validation) | `dss/validators/` | All tests |
| Sensory 👁️ | [Glossary](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems) | [Figma](../tools/figma/) | `tools/figma/` | Figma tests |
| Skin 🎨 | [Glossary](EXTENDED_GLOSSARY.md#-skin-storybook-documentation-ui) | [Storybook](../STORYBOOK_CONFIG.md) | `dss/storybook/` | UI tests |
| Skeleton 🦴 | [Glossary](EXTENDED_GLOSSARY.md#-skeleton-schemas--structure) | [Schemas](../dss-mvp1/dss/models/) | `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](TOKEN_INGESTION.md#extraction-workflow)
- [Component Definition Workflow](../COMPONENT_AUDIT.md)
- [Theme Generation Workflow](../STORYBOOK_CONFIG.md#theme-generation)
- [Deployment Workflow](../DEPLOYMENT.md#deployment-process)

---

## Troubleshooting

### By Symptom

**"The organism is sluggish"** (Slow performance)
- Check database response time
- Monitor CPU/memory usage
- Review API latency
- See: [Performance Guide](PERFORMANCE.md)

**"The organism is confused"** (Validation errors)
- Review error messages from immune system
- Check token schema compliance
- Verify naming conventions
- See: [Validation Guide](CODE_INTEGRATION_GUIDE.md#validation)

**"The organism can't see"** (Figma connection issues)
- Verify Figma token configuration
- Check sensory organs health
- Review Figma API status
- See: [Figma Integration](../tools/figma/README.md)

**"The organism is sick"** (Data integrity issues)
- Run validation checks
- Review recent database operations
- Check for corrupted tokens
- See: [Error Handling](../ERROR_HANDLING.md)

**"The organism is deaf"** (Not receiving updates)
- Check API endpoints
- Verify webhook configuration
- Review event emitters
- See: [Architecture - Communication](ARCHITECTURE.md)

### 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](EXTENDED_GLOSSARY.md).

---

## 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](#getting-started)
→ Read [Organism Framework](#organism-framework)
→ Explore specific system you work on

**Frontend Developers**
→ Focus on [Sensory Organs](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems) and [Skin](EXTENDED_GLOSSARY.md#-skin-storybook-documentation-ui)
→ Read [Code Integration Guide](CODE_INTEGRATION_GUIDE.md)
→ Explore `admin-ui/`, `dss/storybook/`

**Backend Developers**
→ Study [Digestive System](EXTENDED_GLOSSARY.md#-digestive-system-token-ingestion) and [Heart](EXTENDED_GLOSSARY.md#-heart-database-layer)
→ Read [Token Ingestion](TOKEN_INGESTION.md)
→ Explore `dss/ingest/`, `dss/storage/`

**DevOps/Infrastructure**
→ Focus on [Heart](EXTENDED_GLOSSARY.md#-heart-database-layer) and [Architecture](ARCHITECTURE.md)
→ Read [Deployment](../DEPLOYMENT.md)
→ Monitor system health

**Designers**
→ Read [Quick Start](QUICK_START_ORGANISM.md)
→ Explore [Sensory Organs](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems)
→ Visit [Storybook Guide](../STORYBOOK_CONFIG.md)

### By Problem Type

**"I don't understand how X works"**
→ Check [Extended Glossary](EXTENDED_GLOSSARY.md)
→ Read the corresponding system guide
→ Look at code examples in [Code Integration Guide](CODE_INTEGRATION_GUIDE.md)

**"I'm getting an error"**
→ Read the error message carefully
→ Look up the term in [Extended Glossary](EXTENDED_GLOSSARY.md)
→ Check [Troubleshooting](#troubleshooting)
→ See [Error Handling](../ERROR_HANDLING.md)

**"I need to add a new feature"**
→ Find similar existing feature
→ Review [Architecture](ARCHITECTURE.md)
→ Check [How-To Guides](#how-to-guides)
→ Look at test examples

**"The system seems broken"**
→ Run health check: `python -m dss.settings check-deps`
→ Check [Troubleshooting](#troubleshooting)
→ Review logs in [Logger](EXTENDED_GLOSSARY.md#-logger-consciousness)
→ 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](EXTENDED_GLOSSARY.md) first
- Review [Troubleshooting](#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](DSS_ORGANISM_GUIDE.md) - Full framework
- [📚 Quick Reference Glossary](DSS_BIOLOGY_GLOSSARY.md) - Quick lookup
- [🔧 Code Integration Guide](CODE_INTEGRATION_GUIDE.md) - How to use in code
- [📊 Architecture](ARCHITECTURE.md) - System design
- [🐛 Troubleshooting](TROUBLESHOOTING.md) - Problem solving

---

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

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