docs/ARCHITECTURE.md

WidgetBoard Architecture

Overview

WidgetBoard is an enterprise-grade, widget-based dashboard platform built with React, TypeScript, and modern web technologies. The architecture is designed for security, scalability, and maintainability.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         Browser Client                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Widgets    │  │  Components  │  │   Contexts   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│         │                  │                  │                  │
│         └──────────────────┴──────────────────┘                 │
│                           │                                      │
│         ┌─────────────────┴─────────────────┐                  │
│         │                                     │                  │
│  ┌──────▼──────┐                    ┌────────▼─────┐           │
│  │ MCP Client  │◄───────────────────┤    Logger    │           │
│  └─────────────┘                    └──────────────┘           │
│         │                                                        │
│         │ WSS (Secure WebSocket)                               │
├─────────┼────────────────────────────────────────────────────┤
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────┐                                               │
│  │ MCP Server  │ (External Service)                           │
│  └─────────────┘                                               │
│         │                                                        │
│         ├──────► Microsoft Graph API (Outlook Integration)     │
│         ├──────► Gemini AI API (AI Features)                   │
│         └──────► Other Data Sources                            │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. Application Layer

• Root application with context providers
• Shell with header, sidebar, and dashboard
• Widget initialization and management

2. Widget System

• Central registry for widget definitions
• Dynamic widget loading and lifecycle
• 10+ specialized widgets (Chat, Email RAG, Performance Monitor, etc.)

3. Security Layer

• Input sanitization and validation
• Rate limiting and circuit breaker
• JWT authentication
• Sensitive data redaction

4. Communication Layer

• MCP Client with WebSocket
• Automatic reconnection
• Request/response handling
• Event subscription

5. Logging System

• Structured logging with context
• Multiple transports
• Performance monitoring
• Sensitive data protection

Data Flow

User Action → Widget → Context → MCP Client → WebSocket → Server → Response → Update UI

Security Architecture

Defense in Depth

1. Input sanitization (XSS, SQLi prevention)
2. WSS with JWT authentication
3. RBAC and feature flags
4. Data encryption and redaction

Circuit Breaker Pattern

• CLOSED: Normal operation
• OPEN: Reject requests after failures
• HALF_OPEN: Test recovery

Performance Targets

• FCP: < 1.5s
• LCP: < 2.5s
• TTI: < 3.5s
• Test Coverage: 70%+

See full documentation in docs/ directory.