276ed71f31
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
279 lines
10 KiB
Markdown
279 lines
10 KiB
Markdown
# 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
|