# ADR-006: Multi-Project System Design

## Status
Accepted

## Context
CMS-aiChemist was initially conceived as tooling for a specific project, but the underlying problem it solves is universal:

- Visual design and frontend implementation are often disconnected
- Design-to-code workflows require manual translation
- Token extraction from design tools is repetitive
- Component libraries need consistent maintenance across projects
- Documentation and specifications drift from implementation

The architecture being built (NotebookLM brain, Penpot integration, token pipeline, CSA delivery, ADW intake) is not project-specific. These are general-purpose orchestration patterns.

Key realization: CMS-aiChemist is not a single-project tool. It's a multi-project orchestration system for visual design and frontend work across any existing, new, or future projects.

## Decision
Design all architecture and tooling as project-agnostic from the start. CMS-aiChemist is an orchestration platform that works across multiple projects, not a monolithic application.

### System Design Principles
1. **Project parameterization**: Token pipeline, component library, and brain integration must accept project context as input
2. **Modular entry points**: The system serves internal users, external clients, autonomous agents, and other projects
3. **Standardized workflow**: Research → Design → Tokens → Implementation → Content → Delivery applies to any project
4. **Pilot-based validation**: Test the orchestration flow on specific pilot projects, but design the tools to work generically
5. **Hub-and-spoke architecture**: NotebookLM brain at the center, with project-specific contexts as spokes

### Current Implementation
The pilot projects validate the multi-project pattern:
- **Pilot A** (Issue #1): CMS marketing page - Astro + EmDash
- **Pilot B** (Issue #2): Interactive dashboard - Next.js
- **ICP E2E Tests**: 4 distinct ICP projects (50 tokens, 4 components, 4 routes)
- **Kaleido-Life**: Cross-project token population (129 DTCG tokens)
- **Stitch Integration**: Design-to-code workflow exercised across multiple screens

Each pilot uses the same orchestration flow but produces different artifacts for different projects.

## Consequences

### Positive
- **Scalability**: System design prepares for 10+ projects, not just 1-2 pilots
- **Reusability**: Token pipeline, brain integration, CSA templates work for any project
- **Learning**: Each project run improves the orchestration tooling for all future projects
- **Flexibility**: New projects can plug into existing infrastructure without rearchitecture
- **Market positioning**: Platform serves internal projects AND external clients

### Negative
- **Complexity**: Must design for parameterization and project context switching
- **Testing burden**: Changes must validate across multiple project contexts
- **Documentation**: Need to explain "how to onboard a new project" not just "how to use the tool"
- **State management**: Brain must track multiple projects, not assume single-project context

### Neutral
- **Current projects in system**:
  - CMS-aiChemist itself (meta-project)
  - Pilot A (Astro marketing)
  - Pilot B (Next.js dashboard)
  - Kaleido-Life (token extraction)
  - 4 ICP test projects (E2E validation)
- **Project metadata needed**: name, design source (Penpot/Stitch), target framework, token namespace, delivery format
- **NotebookLM sources**: Can be project-scoped or system-scoped

### Architectural Implications
- **Token pipeline**: Must support namespacing (projectA.color.primary vs projectB.color.primary)
- **Component library**: Consider project-specific variants or composition patterns
- **Brain queries**: Must accept project context ("for project X, what is the token naming convention?")
- **CSA artifacts**: Templates must generate project-aware briefings and source bundles
- **ADW routing**: Issues must be tagged with project context for proper agent dispatch

### Onboarding Pattern (Future)
When a new project is added:
1. Create NotebookLM sources for project specs and research
2. Configure Penpot project or Stitch project ID
3. Set up token namespace and extraction rules
4. Define target framework and component requirements
5. Create ADW routing rules for project-specific issues
6. Generate CSA templates for project delivery format

### Validation Evidence
The E2E test projects (all 5 tests passed) demonstrate the multi-project pattern works:
- Different design sources (Penpot, Stitch)
- Different token counts (50-129 tokens per project)
- Different component types (4-9 components)
- Different route patterns (4-9 routes)
- Same orchestration tools (brain, CSA, ADW, token pipeline)