Add dashboard plan document

DASH_PLAN.md

@@ -0,0 +1,283 @@
+# Detailed Dashboard Implementation Plan
+
+## Project Vision: Unified Statistics Dashboard System
+
+### Vision Statement
+The Statistics Dashboard System represents a transformative approach to website analytics management, designed to serve 100+ websites through an elegant, secure, and scalable solution. By leveraging our existing Matomo statistics server and implementing individual dashboard containers, we're creating a powerful ecosystem that delivers real-time insights while maintaining strict data segregation and access control.
+
+### Strategic Value
+- **Seamless Integration**: Website owners access statistics through their own domain at website.com/dashboard
+- **Single Sign-On**: Integration with existing Google Workspace accounts
+- **Perfect Isolation**: Containerized architecture ensures complete separation between websites
+- **Scalable Design**: System effortlessly scales as new websites are added
+
+### Technical Innovation
+- **Modern Stack**:
+  - React 18 with Tailwind CSS
+  - WebSocket connections for real-time updates
+  - Intelligent caching strategies
+  - Docker-based deployment
+  - Caddy reverse proxy integration
+
+- **Administration System**:
+  - Dual-layer approach
+  - Centralized control for system administrators
+  - Delegated authority for website owners
+  - Reduced support overhead
+
+### Expected Outcomes
+
+#### Immediate Benefits
+- Zero-configuration analytics access for website owners
+- Real-time visitor insights and engagement metrics
+- Secure, role-based access control through existing Google Workspace accounts
+- Automated deployment and scaling through Docker infrastructure
+
+#### Long-term Value
+- Reduced support and maintenance overhead
+- Scalable infrastructure ready for future growth
+- Enhanced security through standardized access controls
+- Improved client satisfaction through ownership of analytics data
+
+### Resource Efficiency
+The containerized architecture maximizes hardware utilization while minimizing operational overhead. Each dashboard container requires minimal resources, sharing the existing infrastructure with our Matomo installation. The standardized deployment process means new websites can be onboarded in minutes rather than hours.
+
+### Implementation Timeline
+12-week development timeline:
+- Week 4: Initial prototypes available for testing
+- Weeks 5-12: Phased rollout and refinement based on user feedback
+
+## Technical Implementation Details
+
+### 1. System Architecture
+
+#### Docker Container Structure
+```
+website-dashboard/
+├── Dockerfile
+├── docker-compose.yml
+├── src/
+│   ├── components/
+│   ├── pages/
+│   ├── services/
+│   └── utils/
+└── nginx.conf
+```
+
+#### Docker Configuration Example
+```yaml
+# Docker Compose for Dashboard
+version: '3'
+services:
+  dashboard:
+    build: .
+    ports:
+      - "::PORT_NUMBER::"
+    volumes:
+      - ./config:/app/config
+    environment:
+      - MATOMO_API_URL=http://matomo:5000
+      - WEBSITE_ID=::WEBSITE_ID::
+    networks:
+      - matomo_network
+      - caddy_network
+```
+
+#### Frontend Structure
+```
+src/
+├── components/
+│   ├── StatisticsCard.tsx
+│   ├── VisitorGraph.tsx
+│   ├── UserManagement.tsx
+│   └── RealTimeUpdates.tsx
+├── pages/
+│   ├── Dashboard.tsx
+│   ├── AdminPanel.tsx
+│   └── UserSettings.tsx
+├── services/
+│   ├── matomoApi.ts
+│   ├── authService.ts
+│   └── websocketService.ts
+└── utils/
+    ├── caching.ts
+    └── dateFormatters.ts
+```
+
+### 2. Authentication Implementation
+
+#### Google Cloud Identity Setup
+```typescript
+// authConfig.ts
+export const googleAuthConfig = {
+  apiKey: process.env.GOOGLE_API_KEY,
+  authDomain: '${websiteId}.firebaseapp.com',
+  projectId: '${websiteId}',
+  scopes: ['email', 'profile']
+};
+```
+
+#### User Authorization Schema
+```typescript
+interface WebsiteAuth {
+  websiteId: string;
+  domain: string;
+  authorizedEmails: string[];
+  adminEmails: string[];
+  settings: {
+    refreshInterval: number;
+    defaultDateRange: string;
+  }
+}
+```
+
+#### Admin Interface Features
+
+**Super Admin Dashboard**:
+- Website Management Panel
+- User Authorization Matrix
+- System Health Monitoring
+- Global Settings Configuration
+
+**Website Owner Dashboard**:
+- User Management Interface
+- Statistics Customization
+- Report Scheduling
+- Access Logs
+
+### 3. Data Flow Architecture
+
+#### Matomo API Integration
+```typescript
+// services/matomoApi.ts
+export class MatomoService {
+  private baseUrl: string;
+  private websiteId: string;
+  private cache: Cache;
+
+  async getVisitorStats(period: string): Promise<VisitorStats> {
+    const cacheKey = `stats_${this.websiteId}_${period}`;
+    const cached = await this.cache.get(cacheKey);
+    
+    if (cached) return cached;
+
+    const data = await this.fetchFromMatomo(`/api/stats/${period}`);
+    await this.cache.set(cacheKey, data, 300); // 5 minute cache
+    return data;
+  }
+}
+```
+
+#### WebSocket Implementation
+```typescript
+// services/websocket.ts
+export class RealTimeUpdates {
+  private ws: WebSocket;
+  private reconnectAttempts: number = 0;
+
+  constructor(websiteId: string) {
+    this.ws = new WebSocket(`wss://your-domain.com/ws/${websiteId}`);
+    this.setupListeners();
+  }
+
+  private setupListeners() {
+    this.ws.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+      this.updateDashboard(data);
+    };
+  }
+}
+```
+
+### 4. Dashboard Components
+
+#### Key Metrics Display
+```typescript
+// components/StatisticsCard.tsx
+interface StatisticsCardProps {
+  title: string;
+  value: number;
+  change: number;
+  period: string;
+  loading: boolean;
+}
+
+export const StatisticsCard: React.FC<StatisticsCardProps> = ({
+  title,
+  value,
+  change,
+  period,
+  loading
+}) => {
+  return (
+    <div className="p-4 bg-white rounded-lg shadow">
+      {/* Component implementation */}
+    </div>
+  );
+}
+```
+
+#### Real-time Visitor Graph
+```typescript
+// components/VisitorGraph.tsx
+import { Line } from 'react-chartjs-2';
+
+export const VisitorGraph: React.FC<{
+  data: VisitorData[];
+  period: string;
+}> = ({ data, period }) => {
+  // Graph implementation
+}
+```
+
+### 5. Deployment Strategy
+
+#### Caddy Configuration
+```
+# Caddyfile addition
+website.com {
+    handle /dashboard/* {
+        reverse_proxy localhost:PORT {
+            header_up Host {host}
+            header_up X-Real-IP {remote_host}
+        }
+    }
+}
+```
+
+#### Monitoring Setup
+```typescript
+// monitoring/health.ts
+export const healthCheck = {
+  matomo: async () => {
+    // Health check implementation
+  },
+  cache: async () => {
+    // Cache check implementation
+  },
+  auth: async () => {
+    // Auth service check implementation
+  }
+};
+```
+
+### 6. Testing Strategy
+
+#### Unit Tests
+```typescript
+// __tests__/components/StatisticsCard.test.tsx
+describe('StatisticsCard', () => {
+  it('renders loading state correctly', () => {
+    // Test implementation
+  });
+
+  it('displays correct formatting for large numbers', () => {
+    // Test implementation
+  });
+});
+```
+
+#### Additional Testing Layers
+- Integration Tests
+- End-to-End Tests
+- Performance Testing