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

278
.knowledge/adrs/ADR_KNOWLEDGE_MAP.md Normal file
View File

@@ -0,0 +1,278 @@
# ADR Knowledge Map
**Visual and textual guide to how DSS architecture connects principles → decisions → implementation**
Use this to understand the knowledge graph and trace decisions back to foundational principles.
---
## Knowledge Graph Structure
```
┌─────────────────────────────────────────────────────────────────┐
│ PRINCIPLES.md (Tier 1) │
│ 7 governance principles that guide all architectural decisions │
└────────────────────┬────────────────────────────────────────────┘
│
│ "Linked via ADR principles: field"
↓
┌─────────────────────────────────────────────────────────────────┐
│ .knowledge/adrs/ (Architecture Decisions) │
│ │
│ ADR-001: Use Markdown ADRs for DSS Architecture Decisions │
│ ├─ Principles: [Knowledge Persistence, SSoT] │
│ ├─ Status: Accepted │
│ └─ Implementation: This ADR system itself │
│ │
│ ADR-002+: [Future decisions captured here] │
│ ├─ Each linked to 1-3 principles │
│ ├─ Traces to specific PRs via PR template │
│ └─ Becomes searchable knowledge graph │
└────────┬────────────────────────────────────────────────────────┘
│
│ "Linked via PR template: Implements ADR-NNN"
↓
┌─────────────────────────────────────────────────────────────────┐
│ Pull Requests & Code Review │
│ │
│ PR #123: Implement caching strategy (ADR-002) │
│ └─ "Implements ADR-002" │
│ └─ "Supports [Single Source of Truth]" │
│ │
│ PR #124: Add API versioning (ADR-003) │
│ └─ "Implements ADR-003" │
│ └─ "Supports [Foundational Contracts]" │
└────────┬────────────────────────────────────────────────────────┘
│
│ "Code implements the decision"
↓
┌─────────────────────────────────────────────────────────────────┐
│ Code & Implementation │
│ │
│ src/cache/sqlite.ts — Implements caching from ADR-002 │
│ src/api/v2/... — Implements versioning from ADR-003 │
│ server/routes/mcp.js — All MCP tools expose operations │
│ │
│ Everything traceable back to: Which principle? Which decision? │
└─────────────────────────────────────────────────────────────────┘
```
---
## How to Trace a Decision
**Starting from a principle:**
1. Which ADRs link to this principle? (Search: `grep -r "principles:" .knowledge/adrs/`)
2. Which PRs implement those ADRs? (Search PR descriptions for "Implements ADR-NNN")
3. Which code files are changed in those PRs? (Check the PR diff)
4. **Result**: You have the full chain from principle to code
**Example trace:**
```
Principle: "Single Source of Truth"
↓
ADR-002: "Use SQLite for local caching" (links to SSoT)
↓
PR #98: "Implement caching layer" (Implements ADR-002)
↓
Files: src/cache/sqlite.ts, src/cache/manager.ts, tests/cache.test.ts
```
**Starting from code:**
1. What PR changed this file? (Git log or GitHub blame)
2. What ADR does the PR reference? (Check PR description)
3. What principles motivated this ADR? (Check ADR frontmatter)
4. **Result**: You understand the "why" behind the code
---
## Current State (Pilot Phase)
### Established ADRs
| ID | Title | Principles | Status | Implementation |
|---|---|---|---|---|
| 001 | Use Markdown ADRs for DSS Architecture Decisions | Knowledge Persistence, Single Source of Truth | Accepted | This system |
### In Progress / To Be Created
During the dss_sync_figma pilot (Weeks 2-4 of December 2025):
- **ADR-002**: Figma API authentication strategy (Phase 5A decision)
- **ADR-003**: Caching strategy for Figma data
- **ADR-004**: Async library choice for Python operations
- **ADR-005+**: Additional dss_sync_figma decisions
Each will:
- Be created by the pilot team as significant decisions are made
- Link to 1-3 DSS principles
- Be referenced in PRs via PR template
- Become part of the queryable knowledge graph
---
## Querying the Knowledge Graph
### Find ADRs by Principle
```bash
# Find all ADRs mentioning "Single Source of Truth"
grep -r "Single Source of Truth" .knowledge/adrs/
# Find all ADRs related to MCP First
grep -r "MCP First" .knowledge/adrs/
# Find all deprecated ADRs
grep -r "status: Deprecated" .knowledge/adrs/
```
### Find Code by ADR
```bash
# Find PRs implementing ADR-002
git log --all --grep="ADR-002" --oneline
# Find code files changed in ADR-002's PRs
git log --all --grep="ADR-002" --name-only
```
### Find Principles in Code
```bash
# Find comments referencing a principle
grep -r "Single Source of Truth" src/
# Find TODOs about principle compliance
grep -r "TODO.*SSoT" .
```
---
## Example: Complete Trace
### Scenario: "Why do we cache Figma data this way?"
**Step 1: Find the ADR**
```bash
$ grep -r "cache" .knowledge/adrs/ --ignore-case
.knowledge/adrs/ADR-002-figma-caching-strategy.md
→ ADR-002 explains: Use in-memory cache with SQLite persistence
```
**Step 2: Read the ADR**
```markdown
---
id: 002
title: Figma Data Caching Strategy
principles: [Single Source of Truth, Knowledge Persistence]
---
## Decision
Cache Figma data in memory with periodic SQLite persistence.
Prevents API rate limiting and supports offline mode.
## Consequences
- Positive: Fast queries, resilience to API outages
- Negative: Stale data window (up to 5 minutes between syncs)
```
**Step 3: Find the implementation PR**
```bash
$ git log --all --grep="ADR-002"
Commit: "Implement Figma caching (Implements ADR-002)"
```
**Step 4: Find the code**
```bash
$ git show <commit> --name-only
src/services/figma-cache.ts
src/models/figma-cache.model.ts
tests/figma-cache.test.ts
```
**Step 5: Read the code**
```typescript
// src/services/figma-cache.ts
// Implements: ADR-002 Figma Data Caching Strategy
// Principles: Single Source of Truth (one cache per resource),
// Knowledge Persistence (decisions captured in ADR-002)
```
**Result**: You understand not just *how* (the code) but *why* (the principle), *what alternatives* were considered (the ADR), and *who made the decision* (the PR).
---
## Building Your Own Traces
### For Decision-Makers
When you face a decision:
1. Check if a similar ADR already exists
2. If yes: read it; understand the tradeoff; apply same pattern if appropriate
3. If no: create a new ADR linking to relevant principles
4. Record your decision while fresh, before implementation
### For Code Reviewers
When reviewing a PR:
1. Check the PR template's "DSS Principles Check" section
2. Verify the ADR referenced actually exists and is relevant
3. Verify principle alignment claims are justified
4. Ask: "Does this PR implement a decision that should have an ADR?"
### For New Team Members
To onboard:
1. Read `/docs/01_core/PRINCIPLES.md` (the constitution)
2. Read `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md` (explains the system)
3. Grep the ADRs for decisions related to your area
4. Follow traces from ADRs → PRs → code to understand the "why"
---
## Knowledge Graph Evolution
**Year 1 (Current)**:
- Manual ADR creation and discovery
- Grep-based queries
- Cross-links in Markdown
**Year 2 (Planned)**:
- Automated ADR discovery dashboard
- Principle adoption metrics
- Visual knowledge graph with node queries
**Year 3 (Vision)**:
- ADRs generate code contracts (TypeScript types from architecture)
- ADRs auto-validate code against recorded constraints
- ML-based decision suggestions ("You've made similar decisions before")
---
## Related Documents
- **Principles**: `/docs/01_core/PRINCIPLES.md`
- **Core Reference**: `.knowledge/adrs/PRINCIPLES_CORE_REFERENCE.md`
- **ADR Template**: `.knowledge/adrs/000-template.md`
- **ADR Guide**: `.knowledge/adrs/README.md`
- **Example ADR**: `.knowledge/adrs/001-use-markdown-adrs-for-dss-architecture-decisions.md`
---
## Quick Links for Pilot Phase
During dss_sync_figma pilot (Weeks 1-4):
- **Kickoff materials** (archived): `.knowledge/adrs/archived/operational/KICKOFF_AGENDA.md`
- **PR template update** (archived): `.knowledge/adrs/archived/operational/PR_TEMPLATE_UPDATE.md`
- **Facilitator guide** (archived): `.knowledge/adrs/archived/operational/FACILITATOR_GUIDE.md`
- **Slack announcement** (archived): `.knowledge/adrs/archived/operational/SLACK_ANNOUNCEMENT_TEMPLATE.md`
- **Execution checklist** (archived): `.knowledge/adrs/archived/operational/EXECUTION_CHECKLIST.md`
All archived files are still available for reference; they're just not in the main working directory.
---
**Last Updated**: 2025-12-08
**Purpose**: Navigate the DSS knowledge graph
**Audience**: All DSS team members, Zen chat context