bmad-elsabro 1.0.0

package/docs/developer/architecture.md

@@ -0,0 +1,563 @@
+# BMAD Studio Architecture
+
+This document describes the technical architecture of BMAD Studio, the Electron-based desktop application for the BMAD Method.
+
+## Overview
+
+BMAD Studio is a cross-platform desktop application built with:
+
+- **Electron** — Cross-platform desktop framework
+- **React** — UI component library with hooks
+- **TypeScript** — Type-safe JavaScript
+- **Vite** — Fast build tool and dev server
+- **TailwindCSS** — Utility-first CSS framework
+- **Monaco Editor** — VS Code's code editor
+- **ReactFlow** — Visual workflow graph library
+- **Better-SQLite3** — Embedded database for analytics
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    BMAD Studio Application                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                               │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │           Renderer Process (React/Vite)             │    │
+│  ├─────────────────────────────────────────────────────┤    │
+│  │                                                      │    │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │    │
+│  │  │  Chat Panel  │  │   Workflow   │  │ Terminal │ │    │
+│  │  │              │  │    Editor    │  │          │ │    │
+│  │  └──────────────┘  └──────────────┘  └──────────┘ │    │
+│  │                                                      │    │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │    │
+│  │  │ Token Monitor│  │ Test Center  │  │ Settings │ │    │
+│  │  │              │  │              │  │          │ │    │
+│  │  └──────────────┘  └──────────────┘  └──────────┘ │    │
+│  │                                                      │    │
+│  │              Monaco Editor Integration               │    │
+│  │                                                      │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                           ↕                                  │
+│                      IPC Bridge                              │
+│                    (Preload Script)                          │
+│                           ↕                                  │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │             Main Process (Node.js)                  │    │
+│  ├─────────────────────────────────────────────────────┤    │
+│  │                                                      │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │           IPC Handlers                       │  │    │
+│  │  │  • Config  • File Ops  • Terminal           │  │    │
+│  │  │  • Token   • Workflow   • Party Mode        │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  │                                                      │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │           Core Services                      │  │    │
+│  │  │  • Token Tracker    • Workflow Router       │  │    │
+│  │  │  • AI Test Gen      • Project Detector      │  │    │
+│  │  │  • Legacy Migrator  • Party Coordinator     │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  │                                                      │    │
+│  │  ┌──────────────────────────────────────────────┐  │    │
+│  │  │         Database (SQLite)                    │  │    │
+│  │  │  • Token Analytics  • Usage History          │  │    │
+│  │  └──────────────────────────────────────────────┘  │    │
+│  │                                                      │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                                                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Process Architecture
+
+### Main Process
+
+The main process (`electron/main.ts`) is responsible for:
+
+- Creating and managing application windows
+- Setting up IPC handlers for secure communication
+- Managing application lifecycle events
+- Coordinating with core services
+- Handling file system operations
+- Managing global keyboard shortcuts
+
+**Key Features:**
+
+- **Security First**: `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true`
+- **Development Mode**: Auto-opens DevTools, hot reload via Vite
+- **Production Mode**: Loads built files from `dist/`
+
+### Preload Script
+
+The preload script (`electron/preload.ts`) creates a secure bridge between renderer and main processes:
+
+- Exposes safe APIs to the renderer via `window.electronAPI`
+- Uses `contextBridge` for secure IPC communication
+- Implements typed interfaces for all exposed APIs
+- No direct Node.js access in renderer
+
+### Renderer Process
+
+The renderer process (`renderer/`) contains the React application:
+
+- Built with Vite for fast development
+- TypeScript for type safety
+- TailwindCSS for styling
+- Component-based architecture
+- React Context for state management
+
+## Directory Structure
+
+```
+bmad-method/
+├── electron/                    # Main process code
+│   ├── main.ts                 # Application entry point
+│   ├── preload.ts              # IPC bridge
+│   ├── tsconfig.json           # TypeScript config for main
+│   ├── ipc/                    # IPC handlers
+│   │   ├── terminal-handler.ts
+│   │   ├── token-handler.ts
+│   │   ├── workflow-handler.ts
+│   │   ├── party-handler.ts
+│   │   ├── project-detector-handler.ts
+│   │   ├── legacy-migrator-handler.ts
+│   │   └── workflow-router-handler.ts
+│   ├── services/               # Core business logic
+│   │   ├── token-tracker.ts
+│   │   ├── token-cache.ts
+│   │   ├── token-modes.ts
+│   │   ├── budget-alerts.ts
+│   │   ├── ai-test-generator.ts
+│   │   ├── coverage-parser.ts
+│   │   ├── project-detector.ts
+│   │   ├── legacy-migrator.ts
+│   │   ├── party-coordinator.ts
+│   │   ├── workflow-router.ts
+│   │   └── workflow-storage.ts
+│   └── database/               # SQLite database
+│       └── token-analytics.db
+│
+├── renderer/                   # Renderer process (React)
+│   ├── index.html             # HTML entry point
+│   ├── index.tsx              # React entry point
+│   ├── App.tsx                # Main React component
+│   ├── tsconfig.json          # TypeScript config for renderer
+│   ├── styles.css             # Global styles
+│   ├── components/            # React components
+│   │   ├── ChatPanel.tsx
+│   │   ├── CodeEditor.tsx
+│   │   ├── Terminal.tsx
+│   │   ├── TokenMonitor.tsx
+│   │   ├── TokenAnalytics.tsx
+│   │   ├── WorkflowEditor.tsx
+│   │   ├── TestCenter.tsx
+│   │   ├── PartyMode.tsx
+│   │   ├── MigrationWizard.tsx
+│   │   ├── FlowSelector.tsx
+│   │   ├── TemplateSelector.tsx
+│   │   ├── OnboardingWizard.tsx
+│   │   ├── NotificationCenter.tsx
+│   │   ├── TutorialOverlay.tsx
+│   │   ├── Sidebar.tsx
+│   │   ├── MessageInput.tsx
+│   │   └── MessageList.tsx
+│   ├── hooks/                 # Custom React hooks
+│   ├── context/               # React Context providers
+│   ├── lib/                   # Utility functions
+│   └── types/                 # TypeScript type definitions
+│
+├── src/                       # Legacy CLI code (being migrated)
+│   ├── bmm/                   # BMad Method core
+│   ├── core/                  # Core utilities
+│   └── utility/               # Utility functions
+│
+├── docs/                      # Documentation
+│   ├── developer/             # Developer documentation
+│   ├── user-guide/            # User guides
+│   ├── explanation/           # Conceptual documentation
+│   ├── how-to/                # How-to guides
+│   ├── reference/             # API reference
+│   └── tutorials/             # Tutorial guides
+│
+└── dist/                      # Build output (gitignored)
+    ├── electron/              # Compiled main process
+    └── renderer/              # Built renderer assets
+```
+
+## Component Architecture
+
+### Core Components
+
+#### ChatPanel
+Handles AI agent interactions with streaming response support.
+
+- Real-time message streaming
+- Agent selection and switching
+- Message history persistence
+- Token usage display per message
+
+#### WorkflowEditor
+Visual workflow creation and editing with drag-and-drop.
+
+- ReactFlow-based graph visualization
+- Step dependency visualization
+- Workflow state persistence
+- Multi-agent "Party Mode" coordination
+
+#### Terminal
+Integrated terminal for running commands.
+
+- Command execution via IPC
+- Output streaming
+- Command history
+- Copy/paste support
+
+#### TokenMonitor
+Real-time token usage tracking with budget alerts.
+
+- Live token consumption display
+- Three efficiency modes: Ultra-Save, Balanced, Power
+- Budget threshold alerts
+- Historical analytics
+
+#### TestCenter
+AI-powered test generation and management.
+
+- AI Test Generator for automated test creation
+- Visual Test Builder for non-programmers
+- Jest integration
+- Coverage dashboard
+
+#### CodeEditor
+Monaco Editor integration for code viewing/editing.
+
+- Offline loading (no CDN)
+- Syntax highlighting for multiple languages
+- IntelliSense and autocomplete
+- File system provider integration
+
+### Layout Components
+
+#### Sidebar
+Collapsible navigation sidebar.
+
+- Navigation menu
+- Quick access to features
+- Collapse/expand animation
+- Persistent state
+
+#### NotificationCenter
+Toast-style notifications for system events.
+
+- Success/error/warning/info types
+- Auto-dismiss with configurable timeout
+- Action buttons (optional)
+- Stack management
+
+## State Management
+
+### React Context
+
+- **ThemeContext**: Dark/light theme toggle
+- **ConfigContext**: Application configuration
+- **WorkflowContext**: Current workflow state
+- **TokenContext**: Token tracking state
+
+### Local State
+
+- Component-level state with `useState`
+- Side effects with `useEffect`
+- Custom hooks for reusable logic
+
+### Persistent State
+
+- Electron Store for application settings
+- SQLite for analytics and historical data
+- File system for workflows and agents
+
+## IPC Communication
+
+### Security Model
+
+All IPC communication follows Electron security best practices:
+
+1. **Context Isolation**: Renderer cannot access Node.js directly
+2. **Preload Bridge**: Safe API exposure via `contextBridge`
+3. **Typed Interfaces**: TypeScript ensures type safety
+4. **Validation**: All inputs validated before processing
+
+### IPC Channels
+
+#### Config Operations
+- `config:get` — Retrieve configuration values
+- `config:set` — Update configuration values
+
+#### File Operations
+- `file:read` — Read file contents
+- `file:write` — Write file contents
+- `file:list` — List directory contents
+
+#### Terminal Operations
+- `terminal:execute` — Execute shell command
+- `terminal:kill` — Kill running process
+
+#### Token Operations
+- `token:track` — Record token usage
+- `token:get-stats` — Retrieve analytics
+- `token:set-mode` — Change efficiency mode
+- `token:set-budget` — Update token budget
+
+#### Workflow Operations
+- `workflow:load` — Load workflow definition
+- `workflow:save` — Save workflow changes
+- `workflow:execute` — Run workflow
+- `workflow:list` — List available workflows
+
+#### Party Mode Operations
+- `party:start` — Initialize party mode session
+- `party:add-agent` — Add agent to party
+- `party:remove-agent` — Remove agent from party
+- `party:send-message` — Send message to party
+
+## Data Storage
+
+### Configuration
+
+Stored in Electron's `userData` directory:
+
+```
+~/.config/bmad-studio/ (Linux)
+~/Library/Application Support/bmad-studio/ (macOS)
+%APPDATA%\bmad-studio\ (Windows)
+```
+
+Configuration file: `.bmad/config.json`
+
+### Token Analytics
+
+SQLite database at: `<userData>/.bmad/token-analytics.db`
+
+**Schema:**
+```sql
+CREATE TABLE token_usage (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp INTEGER NOT NULL,
+  tokens_used INTEGER NOT NULL,
+  mode TEXT NOT NULL,
+  workflow_id TEXT,
+  agent_id TEXT,
+  cost REAL
+);
+
+CREATE INDEX idx_timestamp ON token_usage(timestamp);
+CREATE INDEX idx_workflow ON token_usage(workflow_id);
+```
+
+### Workflows and Agents
+
+Stored in project directory: `.bmad/`
+
+```
+.bmad/
+├── config.json          # Project configuration
+├── workflows/           # Workflow definitions (YAML)
+├── steps/               # Step definitions
+└── agents/              # Agent configurations (YAML)
+```
+
+## Build System
+
+### Development
+
+```bash
+npm run electron:dev
+```
+
+This command:
+1. Watches TypeScript files in `electron/` for changes
+2. Starts Vite dev server on port 5173
+3. Launches Electron with hot reload
+4. Opens DevTools automatically
+
+### Production Build
+
+```bash
+npm run electron:build
+```
+
+This command:
+1. Builds renderer with Vite (`npm run build:renderer`)
+2. Compiles main process TypeScript (`npm run build:electron`)
+3. Packages app with electron-builder for all platforms
+
+### Output
+
+- **Windows**: `.exe` installer
+- **macOS**: `.dmg` disk image
+- **Linux**: `.AppImage` package
+
+## Performance Considerations
+
+### Initial Load Time
+
+Target: <2 seconds
+
+**Optimizations:**
+- Code splitting with React.lazy
+- Monaco Editor loaded on-demand
+- Virtualized lists for large data sets
+- Lazy-load heavy components
+
+### Memory Management
+
+**Strategies:**
+- Virtualized rendering for workflows/files
+- Stream large file reads
+- Clean up event listeners in `useEffect` cleanup
+- Dispose Monaco Editor models when unmounted
+
+### Token Economy
+
+**Caching:**
+- LRU cache for frequent AI responses
+- Cache invalidation on workflow changes
+- Configurable cache size per mode
+
+**Modes:**
+- **Ultra-Save**: 40% token reduction, aggressive caching
+- **Balanced**: Moderate caching, good UX
+- **Power**: Minimal caching, best accuracy
+
+## Security
+
+### Electron Security
+
+- ✅ Context Isolation enabled
+- ✅ Node Integration disabled
+- ✅ Sandbox enabled
+- ✅ Preload script for IPC bridge
+- ✅ Content Security Policy configured
+- ✅ No eval() or inline scripts
+
+### Data Security
+
+- Local storage only (no cloud sync in v1)
+- No credentials stored in plain text
+- File access restricted to user data directory
+- IPC input validation and sanitization
+
+## Testing
+
+### Unit Tests
+
+Jest for all services and utilities:
+
+```bash
+npm test
+```
+
+### Integration Tests
+
+Test IPC communication between main and renderer:
+
+```bash
+npm run test:integration
+```
+
+### E2E Tests
+
+Spectron for end-to-end application testing:
+
+```bash
+npm run test:e2e
+```
+
+## Development Tools
+
+### React DevTools
+
+Install as Chrome extension, accessible via DevTools in development mode.
+
+### Electron DevTools
+
+Automatically opened in development mode for debugging renderer.
+
+### Main Process Debugging
+
+Use VS Code debugger with this launch configuration:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Electron Main",
+  "runtimeExecutable": "npm",
+  "runtimeArgs": ["run", "electron:start"],
+  "port": 9229
+}
+```
+
+## Common Patterns
+
+### Creating a New Component
+
+1. Create file in `renderer/components/`
+2. Export React component with TypeScript types
+3. Use TailwindCSS for styling
+4. Add to main App.tsx layout
+5. Write unit tests
+
+### Adding an IPC Handler
+
+1. Create handler file in `electron/ipc/`
+2. Export setup function (e.g., `setupMyHandlers`)
+3. Call setup function in `main.ts` → `setupIpcHandlers()`
+4. Add types to `renderer/types/electron-api.d.ts`
+5. Expose in `preload.ts`
+
+### Creating a Service
+
+1. Create service file in `electron/services/`
+2. Export service class or functions
+3. Add tests in `test/services/`
+4. Document in API reference
+
+## Troubleshooting
+
+### Monaco Editor Not Loading
+
+**Issue**: Monaco Editor shows blank screen
+
+**Solution**: Ensure local loader configuration is set:
+
+```typescript
+loader.config({
+  paths: { vs: './node_modules/monaco-editor/min/vs' }
+});
+```
+
+### IPC Not Working
+
+**Issue**: Renderer cannot call IPC methods
+
+**Solution**: Check that:
+1. Handler is registered in `main.ts`
+2. API is exposed in `preload.ts`
+3. Types are defined in `electron-api.d.ts`
+
+### Build Fails
+
+**Issue**: TypeScript compilation errors
+
+**Solution**:
+1. Check `tsconfig.json` for correct paths
+2. Ensure all dependencies installed: `npm install`
+3. Clear build cache: `rm -rf dist/`
+
+## Next Steps
+
+- [API Reference](./api-reference.md) — Detailed API documentation
+- [Contributing Guide](./contributing.md) — Development workflow and standards
+- [User Guide](../user-guide/) — End-user documentation