nextcloud-analytics/README.md

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

• Nextcloud app metadata (info.xml, appinfo/info.xml)
• Application bootstrap (App.php, AppInfo.php)
• MVC pattern (Controllers, Services, Models)
• Routes and API endpoints
• Scheduled job framework (cron.php)

✅ Controllers

• ApiV1Controller - REST API endpoints for agent integration
• ReportController - Internal report generation logic

✅ Services (Scaffolds)

• GoogleAnalyticsService - GA4 API wrapper (stub)
• LLMService - Anthropic Claude API (stub)
• DataProcessor - Delta calculations and validation (stub)

✅ Models

• ClientConfig - Client configuration entity
• Report - Report entity

✅ Configuration

• Admin settings template
• 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:

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.