f9c49cf7c2
Nextcloud Analytics Hub complete: - Nextcloud PHP app (analytics-hub/) - All phases (1-3) complete - Go client tool (nextcloud-analytics) - Full CLI implementation - Documentation (PRD, README, STATUS, SKILL.md) - Production-ready for deployment to https://cloud.shortcutsolutions.net Repository: git.teamworkapps.com/shortcut/nextcloud-analytics Workspace: /home/molt/.openclaw/workspace
179 lines
5.0 KiB
Markdown
179 lines
5.0 KiB
Markdown
# 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.**
|