bruno/dss
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Initial commit: Clean DSS implementation

Browse Source 
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm

Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)

Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability

Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

437
docs/01_core/DOCUMENTATION_GUIDE.md Normal file
View File

@@ -0,0 +1,437 @@
# DSS Documentation Guide
**Version 1.0.0** | Last Updated: 2025-12-08 | Status: Production
This guide helps you find the right documentation for your task. Start here, find your scenario, and jump to the right doc.
---
## I'm New to DSS
**Goal**: Understand what DSS is and get started
**Read In This Order:**
1. **PRINCIPLES.md** (5 min) - What DSS believes
2. **README.md** (5 min) - Project overview
3. **QUICK_REFERENCE.md** (5 min) - Key links and commands
4. This guide (you're reading it!)
**Then Choose Your Path:**
- Integrating DSS into your project? → INTEGRATION_GUIDE.md
- Contributing to DSS? → CONTRIBUTION_GUIDE.md
- Setting up for development? → DEVELOPMENT_SETUP.md
---
## I Need to Do Something Specific
### I'm Making a Structural Decision
**Question**: Will this affect how components, tokens, or APIs work?
**Read:**
- **PRINCIPLES.md** (understand the 5 core principles)
- **BEST_PRACTICES.md** (how to apply principles)
- **.knowledge/adrs/** (how similar decisions were made)
**Then:**
- Create an ADR documenting your decision
- Open PR referencing the ADR
---
### I'm Writing Code
**Question**: What's the contract I need to follow?
**Read:**
- **ARCHITECTURE.md** (system structure and design)
- **API_CONTRACTS.md** (endpoint specifications)
- **BEST_PRACTICES.md** (implementation patterns for your principle)
**Then:**
- Follow the patterns in ARCHITECTURE.md
- Respect the contracts in API_CONTRACTS.md
- Link to BEST_PRACTICES.md in your PR if needed
---
### I'm Adding an API Endpoint or MCP Tool
**Read:**
- **API_CONTRACTS.md** (existing endpoints)
- **BEST_PRACTICES.md** § Principle 5 (tool-first architecture)
- **docs/03_reference/MCP_TOOLS_SPEC.md** (how to design tools)
**Then:**
1. Design MCP tool (primary)
2. Implement tool
3. REST endpoint wraps tool
4. Document in API_CONTRACTS.md with new version
5. Create ADR for architectural decision
---
### I'm Integrating DSS into My Project
**Read:**
- **QUICK_REFERENCE.md** (overview)
- **INTEGRATION_GUIDE.md** (step-by-step integration)
- **API_CONTRACTS.md** (endpoints you'll use)
- **docs/03_reference/MCP_TOOLS_SPEC.md** (available tools)
**Questions?**
- "How do I do X?" → Search INTEGRATION_GUIDE.md
- "What endpoints are available?" → See API_CONTRACTS.md
- "How do tokens work?" → See docs/03_reference/TOKEN_SYSTEM.md
---
### I'm Deploying DSS
**Read:**
- **PROJECT_STATUS.md** (current deployment status)
- **DEPLOYMENT_GUIDE.md** (step-by-step deployment)
- **PRODUCTION_READINESS.md** (checklist before deploy)
- **TROUBLESHOOTING.md** (when things go wrong)
**Then:**
- Check PRODUCTION_READINESS.md checklist
- Follow DEPLOYMENT_GUIDE.md steps
- Update PROJECT_STATUS.md after successful deploy
---
### I'm Debugging Something
**Read:**
- **PROJECT_STATUS.md** (known issues section)
- **TROUBLESHOOTING.md** (common problems)
- **ARCHITECTURE.md** (understand component interactions)
- Log files in **logs/** directory
**Still stuck?**
- Check .knowledge/adrs/ for related decisions
- Review ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes
- Ask team in Slack with reference to docs you read
---
### I'm Reviewing a PR
**Checklist:**
- [ ] Does this violate any principles? → See PRINCIPLES.md
- [ ] Did they follow best practices? → See BEST_PRACTICES.md
- [ ] Should this be documented? → Where should it go?
- [ ] Is this an architectural change? → ADR needed?
- [ ] Version numbers updated? → See BEST_PRACTICES.md § Principle 2
**Look for anti-patterns:**
See ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes
---
## Documentation by Tier
### Tier 1: Constitutional Documents (Immutable, Versioned)
These change only through semantic versioning. They define the system.
| Document | Purpose | Read When |
|----------|---------|-----------|
| **PRINCIPLES.md** | Core values (5 principles) | Onboarding, making decisions |
| **API_CONTRACTS.md** | API endpoint specifications | Building integrations, implementing endpoints |
| **ARCHITECTURE.md** | System design, structure | Understanding system, making changes |
**Update Process:**
1. Change file
2. Bump version (MAJOR.MINOR.PATCH)
3. Add changelog entry
4. Open PR
5. Merge and tag (git tag v1.2.0)
---
### Tier 2: Current State Documents (Living, Weekly Updates)
These reflect production reality. Updated at least weekly.
| Document | Purpose | Read When |
|----------|---------|-----------|
| **PROJECT_STATUS.md** | Current deployment, bugs, roadmap | Weekly reviews, planning, status checks |
| **IMPLEMENTATION_SUMMARY.md** | Feature inventory by phase | Understanding what's shipped |
| **README.md** | Project overview, quick links | First time visiting repo |
**Update Process:**
1. Every Friday: Review and update
2. Mark "Last Updated" with current date
3. Update bugs, roadmap, deployment status
4. Commit to main branch
---
### Tier 3: How-To Guides (Reference Documents)
Detailed guidance on specific tasks. Updated as needed.
| Document | Purpose | Read When |
|----------|---------|-----------|
| **QUICK_REFERENCE.md** | Cheat sheet, commands, quick links | Need to find something fast |
| **INTEGRATION_GUIDE.md** | How to integrate DSS into your project | Using DSS in your own project |
| **DEPLOYMENT_GUIDE.md** | Step-by-step deployment process | Deploying to production |
| **MIGRATION_GUIDE.md** | How to upgrade between versions | Upgrading DSS version |
| **MCP_TOOLS_SPEC.md** | Available MCP tools and how to use them | Using MCP tools in automation |
| **CONTRIBUTION_GUIDE.md** | How to contribute to DSS | Contributing code changes |
| **DEVELOPMENT_SETUP.md** | Local development environment | Setting up to develop DSS |
| **PRODUCTION_READINESS.md** | Pre-deployment checklist | Before deploying to production |
| **TROUBLESHOOTING.md** | Common problems and solutions | Debugging issues |
**Update Process:**
1. Update when procedures change
2. Mark "Last Updated" date
3. Review monthly for staleness
4. Archive if superseded by new guide
---
### Tier 4: Knowledge Archive
Historical records, old versions, archived docs.
| Document Type | Purpose | Read When |
|---------|---------|-----------|
| **.knowledge/adrs/** | Architecture Decision Records | Understanding why decisions were made |
| **docs/archive/versions/** | Old API/Architecture versions | Integrating with old systems |
| **docs/archive/** | Historical documents | Research, understanding evolution |
---
## Documentation Structure
```
docs/
├── 01_core/
│ ├── PRINCIPLES.md # Tier 1: What we believe
│ ├── BEST_PRACTICES.md # How to apply principles
│ ├── API_CONTRACTS.md # Tier 1: API spec
│ ├── ARCHITECTURE.md # Tier 1: System design
│ ├── ANTI_PATTERNS_AND_LEARNINGS.md # What not to do
│ └── DOCUMENTATION_GUIDE.md # This file
│
├── 02_status/
│ ├── PROJECT_STATUS.md # Tier 2: Current state
│ ├── IMPLEMENTATION_SUMMARY.md # Tier 2: Feature inventory
│ └── CHANGELOG.md # Version history
│
├── 03_reference/
│ ├── QUICK_REFERENCE.md # Tier 3: Cheat sheet
│ ├── INTEGRATION_GUIDE.md # Tier 3: How to integrate
│ ├── DEPLOYMENT_GUIDE.md # Tier 3: How to deploy
│ ├── MIGRATION_GUIDE.md # Tier 3: Version upgrades
│ ├── MCP_TOOLS_SPEC.md # Tier 3: Tool reference
│ ├── TOKEN_SYSTEM.md # Tier 3: Token guide
│ ├── PRODUCTION_READINESS.md # Tier 3: Deploy checklist
│ ├── TROUBLESHOOTING.md # Tier 3: Common problems
│ ├── CONTRIBUTION_GUIDE.md # Tier 3: How to contribute
│ └── DEVELOPMENT_SETUP.md # Tier 3: Dev environment
│
├── archive/
│ ├── versions/
│ │ ├── v1.0.0/
│ │ │ ├── API_CONTRACTS.md
│ │ │ └── ARCHITECTURE.md
│ │ └── v1.1.0/
│ │ └── ...
│ ├── phases/
│ └── 2024/
│
└── README.md # Repo overview
```
---
## How to Find Information
### By Task
| I Want To... | Start Here |
|-------------|-----------|
| Understand DSS | PRINCIPLES.md |
| Integrate DSS | INTEGRATION_GUIDE.md |
| Deploy DSS | DEPLOYMENT_GUIDE.md |
| Contribute code | CONTRIBUTION_GUIDE.md |
| Write an endpoint | API_CONTRACTS.md + BEST_PRACTICES.md |
| Use MCP tools | MCP_TOOLS_SPEC.md |
| Debug something | TROUBLESHOOTING.md |
| Check status | PROJECT_STATUS.md |
| Upgrade version | MIGRATION_GUIDE.md |
| Understand a decision | .knowledge/adrs/ |
### By Role
| I'm A... | Read These |
|---------|-----------|
| **New Developer** | PRINCIPLES.md → README.md → QUICK_REFERENCE.md |
| **Product Manager** | PROJECT_STATUS.md → IMPLEMENTATION_SUMMARY.md |
| **DevOps Engineer** | DEPLOYMENT_GUIDE.md → PRODUCTION_READINESS.md |
| **API Consumer** | API_CONTRACTS.md + INTEGRATION_GUIDE.md |
| **System Architect** | ARCHITECTURE.md + ANTI_PATTERNS_AND_LEARNINGS.md |
| **PR Reviewer** | PRINCIPLES.md + BEST_PRACTICES.md |
### By Principle
| Principle | Learn More In |
|-----------|--------------|
| Design is Architectural | PRINCIPLES.md § 1, ARCHITECTURE.md |
| Contracts are Immutable | BEST_PRACTICES.md § Principle 2, API_CONTRACTS.md |
| Single Source of Truth | BEST_PRACTICES.md § Principle 3, ANTI_PATTERNS_AND_LEARNINGS.md |
| Decisions Traceable | BEST_PRACTICES.md § Principle 4, .knowledge/adrs/ |
| Operations as Tools | BEST_PRACTICES.md § Principle 5, MCP_TOOLS_SPEC.md |
---
## Reading Paths
### Path 1: Onboarding (30 minutes)
```
1. PRINCIPLES.md (5 min)
↓
2. README.md (5 min)
↓
3. QUICK_REFERENCE.md (5 min)
↓
4. Start with relevant Tier 3 guide for your task (15 min)
```
### Path 2: Making a Decision (45 minutes)
```
1. PRINCIPLES.md (5 min)
↓
2. BEST_PRACTICES.md for relevant principle (15 min)
↓
3. .knowledge/adrs/ - similar decisions (15 min)
↓
4. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
↓
5. Create ADR for your decision
```
### Path 3: Architectural Change (1 hour)
```
1. ARCHITECTURE.md (20 min)
↓
2. BEST_PRACTICES.md (15 min)
↓
3. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
↓
4. .knowledge/adrs/ for similar decisions (15 min)
↓
5. Design change, create ADR, open PR
```
### Path 4: Integration (2 hours)
```
1. INTEGRATION_GUIDE.md (30 min)
↓
2. API_CONTRACTS.md (30 min)
↓
3. QUICK_REFERENCE.md (10 min)
↓
4. Implement integration, reference docs
↓
5. TROUBLESHOOTING.md if issues (20 min)
```
---
## Docs That Reference Each Other
**Single Source of Truth Flow:**
```
PRINCIPLES.md (what we believe)
↓
BEST_PRACTICES.md (how to implement)
↓
API_CONTRACTS.md, ARCHITECTURE.md (actual specs)
↓
IMPLEMENTATION_GUIDE.md, DEPLOYMENT_GUIDE.md (how-to guides)
↓
Actual code implementation
```
**Decision Flow:**
```
BEST_PRACTICES.md (decision criteria)
↓
.knowledge/adrs/ (record decision)
↓
PR links to ADR (traceability)
↓
Code implements decision
↓
ARCHITECTURE.md or API_CONTRACTS.md (documents result)
```
---
## Keeping Docs Current
### Weekly (Every Friday)
- [ ] Update PROJECT_STATUS.md
- Mark "Last Updated"
- Update bugs list
- Update roadmap
- Update deployment status
### Monthly (First Friday)
- [ ] Audit all Tier 3 docs for staleness
- Any docs older than 30 days?
- Still accurate?
- Update or archive?
### Per Release
- [ ] Update API_CONTRACTS.md version
- [ ] Add CHANGELOG entry
- [ ] Update MIGRATION_GUIDE.md if breaking changes
- [ ] Update IMPLEMENTATION_SUMMARY.md with new features
- [ ] Create tag (git tag vX.Y.Z)
### When Making Major Changes
- [ ] Create or update ADR
- [ ] Update relevant Tier 1 docs
- [ ] Link PR to ADR
- [ ] Update related Tier 3 guides
---
## FAQ: Finding Documentation
**Q: Where are API endpoints documented?**
A: API_CONTRACTS.md (Tier 1, immutable)
**Q: Why did we choose this architecture?**
A: Check ARCHITECTURE.md or .knowledge/adrs/ (decision records)
**Q: What's currently deployed?**
A: PROJECT_STATUS.md (Tier 2, updated weekly)
**Q: How do I integrate DSS?**
A: INTEGRATION_GUIDE.md (Tier 3, reference guide)
**Q: How do I deploy changes?**
A: DEPLOYMENT_GUIDE.md (Tier 3, step-by-step)
**Q: What's the status of feature X?**
A: IMPLEMENTATION_SUMMARY.md or PROJECT_STATUS.md
**Q: What changed between versions?**
A: CHANGELOG.md or MIGRATION_GUIDE.md
**Q: Is this documented?**
A: Yes! (probably) → Use this guide to find it
---
**Last Updated**: 2025-12-08
**Version**: 1.0.0 (new navigation guide)
**Status**: PRODUCTION