# Statistics Engine Technical Plan

## 1. Infrastructure Overview

### Docker Container Stack
- Matomo Analytics Container
  - Official Matomo image
  - Exposed port: 8080
  - Environment: Production
  
- MariaDB Database Container
  - Version: Latest stable
  - Persistent volume for data
  - Restricted network access
  
- Dashboard Frontend Container
  - Next.js application
  - TypeScript + React
  - Tailwind CSS for styling
  - Exposed port: 3001
  
- Existing Infrastructure Integration
  - Portainer (10.4.0.206:9443)
  - Caddy reverse proxy
  - Gitea (gitea.sigd.net)

## 2. Authentication System

### Google Workspace Integration
- Domain: deafgain.org
- Primary Admin: system@deafgain.org
- Authentication Method: Google OAuth 2.0
- Security: APP password implementation
- Scope: email, profile

## 3. Component Details

### A. Matomo Analytics Setup
1. Core Configuration
   - Database: MariaDB
   - Data retention policy
   - API access configuration
   - Website tracking setup
   - GDPR compliance tools

2. Security Measures
   - API token management
   - Rate limiting
   - Access control lists
   - IP anonymization

### B. Dashboard Frontend
1. Technical Stack
   - Next.js 14.1
   - React 19
   - TypeScript 5.7
   - Tailwind CSS 3.4

2. Features
   - Real-time statistics display
   - Historical data visualization
   - Custom date range selection
   - Export capabilities
   - Mobile-responsive design
   - Heatmaps and session recordings
   - E-commerce tracking

3. API Integration
   - Matomo HTTP API
   - Data fetching strategy
   - Error handling
   - Caching implementation
   - Custom dimension support

### C. Database Layer
1. MariaDB Configuration
   - Data structure optimization
   - Automated backup strategy
   - Performance tuning
   - Connection pooling
   - Table partitioning

## 4. Network Configuration

### Caddy Setup
```caddyfile
deafgain.org {
    handle /control* {
        reverse_proxy localhost:3001
    }
    
    handle /analytics* {
        reverse_proxy localhost:8080
    }
}
```

### Docker Networks
1. Frontend Network
   - Dashboard container
   - Caddy reverse proxy

2. Backend Network
   - Matomo container
   - MariaDB container

## 5. Implementation Steps

### Phase 1: Infrastructure Setup
1. Create Docker networks
2. Deploy MariaDB container
3. Configure persistent volumes
4. Set up backup system

### Phase 2: Matomo Deployment
1. Deploy Matomo container
2. Configure database connection
3. Set up initial website tracking
4. Configure privacy settings
5. Test data collection

### Phase 3: Dashboard Development
1. Create Next.js application
2. Implement Google OAuth
3. Develop statistics interface
4. Connect to Matomo API
5. Implement custom reports

### Phase 4: Integration
1. Configure Caddy routing
2. Set up SSL certificates
3. Implement security measures
4. Test end-to-end functionality

## 6. Website Integration

### DeafGain Website Modification
- Add Matomo tracking code to head section:
```javascript
<!-- Matomo -->
<script>
  var _paq = window._paq = window._paq || [];
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="https://[MATOMO-URL]/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', '[SITE-ID]']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->
```

## 7. Monitoring and Maintenance

### Health Checks
- Container status monitoring
- Database performance metrics
- API response times
- Error rate tracking
- Resource usage monitoring

### Backup Strategy
- Daily database backups
- Configuration backups
- Disaster recovery plan
- Archive logs rotation

## 8. Security Considerations

### Access Control
- Role-based access control
- API token management
- Rate limiting
- IP whitelisting
- Two-factor authentication

### Data Protection
- SSL/TLS encryption
- Database encryption
- Regular security audits
- GDPR compliance tools
- Cookie consent management
- Data anonymization

## 9. Future Enhancements

### Potential Features
- Custom metrics tracking
- Advanced segment analysis
- A/B testing integration
- Enhanced e-commerce tracking
- Custom alert system
- Automated reporting

## 10. Documentation Requirements

### Technical Documentation
- System architecture
- API documentation
- Deployment procedures
- Troubleshooting guides
- Performance optimization

### User Documentation
- Dashboard usage guide
- Authentication procedures
- Report generation
- Data interpretation
- Privacy settings management