matomo-web-statistics/DASH_PLAN.md

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

# 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

// authConfig.ts
export const googleAuthConfig = {
  apiKey: process.env.GOOGLE_API_KEY,
  authDomain: '${websiteId}.firebaseapp.com',
  projectId: '${websiteId}',
  scopes: ['email', 'profile']
};

User Authorization Schema

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

// 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

// 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

// 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

// 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

// 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

// __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