# Mini-CMO Analytics Hub - Nextcloud App

**Version**: 1.0.0
**Status**: Phase 1 Complete - Core Structure
**Date**: 2026-02-12

---

## Project Overview

Nextcloud internal PHP application providing Google Analytics 4 reporting with AI-generated client reports. Exposes REST APIs for agent access via nextcloud-integration tools.

---

## Architecture

**Type**: Nextcloud PHP App (Internal Application)
**Framework**: Nextcloud App Framework (OCP)
**Language**: PHP 8.0+
**Database**: Nextcloud Database (via IDBConnection)
**Target Nextcloud**: 25.0+ (https://cloud.shortcutsolutions.net)

---

## App Structure

```
analytics-hub/
├── appinfo/info.xml              # Extended app metadata
├── info.xml                      # Basic app metadata
├── lib/
│   ├── App.php                  # Application bootstrap
│   ├── AppInfo.php              # App metadata class
│   ├── Controller/
│   │   ├── ApiV1Controller.php  # REST API endpoints
│   │   └── ReportController.php # Internal report generation
│   ├── Service/
│   │   ├── GoogleAnalyticsService.php  # GA4 API wrapper
│   │   ├── LLMService.php              # Anthropic Claude API
│   │   └── DataProcessor.php          # Delta calculations
│   └── Model/
│       ├── ClientConfig.php            # Client entity
│       └── Report.php                # Report entity
├── templates/
│   └── admin.php                # Configuration UI
├── config/
│   └── clients.json            # Client configurations
└── cron.php                       # Scheduled jobs
```

---

## Features Implemented (Phase 1)

### ✅ Core Application Structure
- [x] Nextcloud app metadata (info.xml, appinfo/info.xml)
- [x] Application bootstrap (App.php, AppInfo.php)
- [x] MVC pattern (Controllers, Services, Models)
- [x] Routes and API endpoints
- [x] Scheduled job framework (cron.php)

### ✅ Controllers
- [x] ApiV1Controller - REST API endpoints for agent integration
- [x] ReportController - Internal report generation logic

### ✅ Services (Scaffolds)
- [x] GoogleAnalyticsService - GA4 API wrapper (stub)
- [x] LLMService - Anthropic Claude API (stub)
- [x] DataProcessor - Delta calculations and validation (stub)

### ✅ Models
- [x] ClientConfig - Client configuration entity
- [x] Report - Report entity

### ✅ Configuration
- [x] Admin settings template
- [x] Client configuration example (clients.json)

---

## API Endpoints

All endpoints are prefixed with `/apps/analytics-hub/api`

| Endpoint | Method | Description | Status |
|-----------|--------|-------------|---------|
| `/reports` | GET | List all available reports | ✅ |
| `/report/{id}` | GET | Download specific report | ✅ |
| `/generate` | POST | Trigger report generation | ✅ |
| `/status` | GET | App health/status | ✅ |

**Authentication**: Nextcloud app password (to be implemented)

---

## Next Steps (Phase 2)

### Days 4-7: Core Application

- [ ] Complete GoogleAnalyticsService (GA4 API calls)
- [ ] Complete LLMService (API error handling, retry logic)
- [ ] Complete DataProcessor (validation, smart thresholds)
- [ ] Implement database storage for reports
- [ ] Implement WebDAV file operations
- [ ] Create admin settings controller
- [ ] Add authentication middleware

### Days 8-10: Agent Integration

- [ ] Add custom operations to nextcloud-client tool
- [ ] Update SKILL.md with analytics endpoints
- [ ] Test agent-to-app communication
- [ ] Add error handling and validation

### Days 11-12: Deployment & Automation

- [ ] Deploy to Nextcloud server
- [ ] Enable app via Nextcloud UI
- [ ] Configure cron job
- [ ] Production testing
- [ ] User documentation

---

## Technical Details

### Dependencies (Required)
- Google Analytics Data API v1
- Anthropic Claude API (claude-sonnet-4-5-20250929)
- Nextcloud 25.0+

### Configuration Files

**Google OAuth**:
- Client ID: Stored in Nextcloud config
- Client Secret: Stored in Nextcloud config
- Refresh Token: Stored in Nextcloud config (from local auth.py)

**Anthropic API**:
- API Key: Stored in Nextcloud config

**Clients**: `config/clients.json`

### Scheduling

**Cron Job**: Mon-Fri at 7:00 AM
**Implementation**: Nextcloud internal cron system
**Job Class**: `OCA\AnalyticsHub\Cron\DailyReportJob`

---

## Testing

**To test locally**:
1. Copy `analytics-hub/` to Nextcloud apps directory
2. Enable via Settings → Apps → Analytics Hub
3. Configure via admin settings
4. Test API endpoints via curl

**Example API call**:
```bash
curl -H "Authorization: Bearer <app_password>" \
     https://cloud.shortcutsolutions.net/apps/analytics-hub/api/status
```

---

## Notes

- **Architecture Changed**: From external Python (v2.0) to Nextcloud PHP app (v3.0)
- **Agent Integration**: Via REST APIs (nextcloud-integration tools)
- **Scheduling**: Nextcloud internal cron (not system cron)
- **Authentication**: Nextcloud app password
- **Zero External Costs**: Runs inside Nextcloud

---

**Phase 1 Complete - Core structure ready for implementation.**