Kokoro Analytics

Content Creator Analytics Platform

A comprehensive web application for analyzing content creator metrics across Instagram, Facebook, TikTok, and Twitter/X. Built with Laravel 11 and React 18, featuring real-time analytics, engagement scoring, demographic insights, and multi-platform support.

Overview

Kokoro Analytics is a SaaS platform designed to help brands, agencies, and marketers analyze content creators' performance across major social media platforms. The platform provides detailed metrics, engagement analysis, audience demographics, quality scoring, and cost calculations to help make informed decisions about creator partnerships.

Key Features

• Multi-Platform Support: Analyze creators on Instagram, Facebook, TikTok, and Twitter/X
• Comprehensive Metrics: Engagement rates, reach, impressions, follower growth, and more
• Demographic Insights: Audience breakdown by gender, country, city, and age
• Quality Score: Automated 0-100 score evaluating audience quality and engagement
• Cost Calculator: Estimate cost per post based on engagement and reach
• Interactive Charts: Visualize metrics with Recharts
• API Flexibility: Support for mock data, Apify integration, or official social media APIs
• User Roles: Guest access, authenticated users, and admin panel
• Responsive Design: Modern, mobile-friendly interface built with Tailwind CSS

Technology Stack

Backend

• Laravel 11: PHP framework
• MySQL 8.0+: Database (RDS in production)
• Laravel Sanctum: API authentication
• Inertia.js: Server-side routing for SPA experience

Frontend

• React 18: UI library
• TypeScript: Type safety
• Tailwind CSS: Styling
• Recharts: Data visualization
• Heroicons: Icon system
• Vite: Build tool

Infrastructure

• Docker: Containerization
• Caddy: Reverse proxy with automatic SSL
• AWS EC2: Application server
• AWS RDS: Managed MySQL database
• GitHub Actions: CI/CD pipeline

Quick Start

Prerequisites

• PHP 8.2 or higher
• Composer
• Node.js 18+ and npm
• MySQL 8.0+ (or use SQLite for local development)
• Git

Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd kokoro_analytics
   

2. Install PHP dependencies

   composer install
   

3. Install JavaScript dependencies

   npm install
   

4. Configure environment

   cp ENV_TEMPLATE.txt .env
   php artisan key:generate
   

   Edit .env and configure at minimum:

   APP_URL=http://localhost:8000
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=kokoro_analytics
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   

5. Run database migrations

   php artisan migrate
   php artisan db:seed --class=PlanSeeder
   

6. Build frontend assets

   npm run build
   

7. Start development server

   php artisan serve
   

   Visit http://localhost:8000 in your browser.

Using Docker for Local Development

1. Start services

   docker compose up -d
   

2. Run migrations

   docker compose exec app php artisan migrate
   docker compose exec app php artisan db:seed --class=PlanSeeder
   

3. Access the application

   • Application: http://localhost
   • MySQL: localhost:3306

Configuration

Data Sources

Kokoro Analytics supports three data source options, configurable via the admin panel at /settings/api:

Option 1: Mock Data (Default)

• Simulated but realistic data
• Perfect for development and demos
• No cost or API setup required
• Enable with USE_MOCK_DATA=true in .env

Option 2: Apify Integration (Recommended for Production)

• Analyze any public user across platforms
• Monthly subscription: $49-149
• Quick setup (10 minutes)
• No user authorization required
• Configure APIFY_TOKEN in .env

Option 3: Official Social Media APIs

• Free but limited
• Only works with authorized accounts
• Requires complex OAuth setup (1-2 hours)
• Configure platform-specific tokens in .env

Default Admin Credentials

Email: admin@kokoro.com
Password: admin123

Important: Change these credentials immediately in production environments.

Production Deployment

Architecture

• EC2: Application server running Docker containers
• RDS MySQL 8.0: Managed database service
• Caddy: Reverse proxy handling SSL/TLS automatically
• GitHub Actions: Automated deployment on push to main branch

Prerequisites

1. AWS Account with:

   • EC2 instance (Ubuntu 22.04 LTS, minimum 2GB RAM)
   • RDS MySQL 8.0 instance
   • Security Groups configured
   • Domain name (optional but recommended for SSL)

2. GitHub Repository with Actions enabled

3. GitHub Secrets configured:

   • SERVER_HOST: EC2 public IP or domain
   • SERVER_USER: SSH user (typically ubuntu)
   • SSH_PRIVATE_KEY: SSH private key for EC2
   • GHCR_PAT_KOKOROANALYTICS: GitHub Container Registry Personal Access Token

AWS Setup Steps

1. Create EC2 Instance

• AMI: Ubuntu Server 22.04 LTS
• Instance Type: t3.small (2 vCPU, 2GB RAM) recommended
• Security Group: Allow ports 22 (SSH), 80 (HTTP), 443 (HTTPS)
• Storage: 20 GB minimum
• Elastic IP: Recommended for static IP address

2. Create RDS MySQL Instance

• Engine: MySQL 8.4 LTS (or 8.0)
• Instance Class: db.t3.small for production
• Storage: 20 GB minimum with autoscaling
• Database Name: kokoro_analytics
• Security Group: Allow MySQL (port 3306) only from EC2 Security Group
• Public Access: Disabled (private access only)

3. Configure Security Groups

EC2 Security Group (kokoro-ec2-sg):

• SSH (22): Your IP only
• HTTP (80): 0.0.0.0/0
• HTTPS (443): 0.0.0.0/0

RDS Security Group (kokoro-rds-sg):

• MySQL/Aurora (3306): Source = EC2 Security Group ID

4. Initial Server Setup

SSH into your EC2 instance:

ssh -i /path/to/key.pem ubuntu@<EC2_IP>

Install Docker and Docker Compose:

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Clone repository:

cd /home/ubuntu
git clone <repository-url> kokoro-analytics
cd kokoro-analytics

5. Configure Environment Variables

cp ENV_TEMPLATE.txt .env
nano .env

Configure production settings:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=kokoro-db.xxxxx.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_DATABASE=kokoro_analytics
DB_USERNAME=admin
DB_PASSWORD=your_secure_password

DOMAIN=yourdomain.com

# Generate APP_KEY
php artisan key:generate

Important: DB_HOST should be the RDS endpoint without port (:3306).

6. Deploy Application

Manual Deployment:

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

# Pull and start containers
docker compose -f docker-compose.rds.yml pull app
docker compose -f docker-compose.rds.yml up -d

# Run migrations
docker compose -f docker-compose.rds.yml exec app php artisan migrate --force
docker compose -f docker-compose.rds.yml exec app php artisan db:seed --class=PlanSeeder

# Set permissions
docker compose -f docker-compose.rds.yml exec app chown -R www-data:www-data storage bootstrap/cache
docker compose -f docker-compose.rds.yml exec app chmod -R 755 storage bootstrap/cache

Automatic Deployment (Recommended):

The application includes a GitHub Actions workflow (.github/workflows/deploy-rds.yml) that automatically deploys on push to main. Ensure all GitHub Secrets are configured, then:

git push origin main

The workflow will:

1. Build Docker image
2. Push to GitHub Container Registry
3. SSH to EC2
4. Pull latest code and image
5. Restart containers
6. Run migrations
7. Optimize Laravel caches

7. Configure DNS

Point your domain's A record to the EC2 Elastic IP address. Caddy will automatically provision SSL certificates via Let's Encrypt.

Post-Deployment

1. Verify deployment

   docker compose -f docker-compose.rds.yml ps
   docker compose -f docker-compose.rds.yml logs app
   

2. Update admin credentials

   • Login with default credentials
   • Change password immediately

3. Configure API settings

   • Access /settings/api as admin
   • Configure Apify or official APIs
   • Test connections

4. Monitor logs

   docker compose -f docker-compose.rds.yml logs -f app
   docker compose -f docker-compose.rds.yml logs -f caddy
   

HTTPS en desarrollo con ngrok

Para exponer el servidor con HTTPS (útil para OAuth de Instagram/TikTok), configura ngrok:

1. Conectarte al servidor

   ssh kokoro
   

2. Ejecutar el script de setup

   cd /var/www/kokoro_analytics
   NGROK_TOKEN=tu_authtoken bash scripts/setup-ngrok.sh
   

   Obtén tu authtoken en: https://dashboard.ngrok.com/get-started/your-authtoken

3. Ver la URL pública

   curl -s http://localhost:4040/api/tunnels | jq -r '.tunnels[0].public_url'
   

4. Actualizar APP_URL en .env Usa la URL de ngrok (ej: https://abc123.ngrok-free.app) para que OAuth funcione.

5. Actualizar redirect URIs en Instagram/TikTok Developer Console con la URL de ngrok.

ngrok corre como servicio systemd y se reinicia automáticamente tras reinicios del servidor.

Project Structure

kokoro_analytics/
├── app/
│   ├── Console/Commands/        # Artisan commands
│   ├── Http/
│   │   ├── Controllers/         # Application controllers
│   │   └── Middleware/          # HTTP middleware
│   ├── Jobs/                    # Queue jobs
│   ├── Models/                  # Eloquent models
│   └── Services/                # Business logic
│       ├── SaaS/                # SaaS-related services
│       └── SocialMedia/         # Social media API integrations
├── bootstrap/                   # Application bootstrap
├── config/                      # Configuration files
├── database/
│   ├── migrations/              # Database migrations
│   └── seeders/                 # Database seeders
├── docker/                      # Docker configuration
├── public/                      # Public web root
├── resources/
│   ├── js/                      # React/TypeScript frontend
│   │   ├── Components/          # React components
│   │   ├── Layouts/             # Layout components
│   │   ├── Pages/               # Page components
│   │   └── types/               # TypeScript types
│   └── views/                   # Blade templates
├── routes/                      # Route definitions
├── storage/                     # File storage
└── tests/                       # Test suite

Common Commands

Development

# Install dependencies
composer install
npm install

# Run migrations
php artisan migrate

# Build frontend
npm run build
# Or watch for changes
npm run dev

# Clear caches
php artisan optimize:clear
php artisan config:clear
php artisan cache:clear

Production (Docker)

# View logs
docker compose -f docker-compose.rds.yml logs -f app

# Run Artisan commands
docker compose -f docker-compose.rds.yml exec app php artisan <command>

# Restart services
docker compose -f docker-compose.rds.yml restart app

# Update application
git pull origin main
docker compose -f docker-compose.rds.yml pull app
docker compose -f docker-compose.rds.yml up -d
docker compose -f docker-compose.rds.yml exec app php artisan migrate --force

Troubleshooting

Database Connection Issues

• Verify DB_HOST is correct (RDS endpoint without :3306)
• Check RDS Security Group allows connections from EC2
• Ensure EC2 and RDS are in the same VPC
• Verify database credentials

SSL Certificate Issues

• Ensure DOMAIN is set in .env
• Verify DNS A record points to EC2 IP
• Check port 443 is open in Security Group
• Review Caddy logs: docker compose -f docker-compose.rds.yml logs caddy

Permission Issues

docker compose -f docker-compose.rds.yml exec app chown -R www-data:www-data storage bootstrap/cache
docker compose -f docker-compose.rds.yml exec app chmod -R 755 storage bootstrap/cache

GitHub Actions Deployment Fails

• Verify all GitHub Secrets are configured
• Test SSH connection manually
• Ensure Personal Access Token has read:packages and write:packages permissions
• Check workflow logs in GitHub Actions tab

Security Best Practices

1. Never commit .env files (already in .gitignore)
2. Use strong passwords for RDS (minimum 16 characters, mixed case, numbers, symbols)
3. Configure Security Groups correctly:
   • EC2: Only expose ports 80, 443, 22
   • RDS: Only allow connections from EC2 Security Group
4. Use Elastic IP for static IP address
5. Update Docker images regularly
6. Enable RDS automated backups
7. Limit SSH access to your IP in Security Group
8. Rotate credentials periodically
9. Monitor logs for suspicious activity
10. Keep dependencies updated

Database Backups

Manual Backup

mysqldump -h <RDS_ENDPOINT> -u <USER> -p <DATABASE> > backup_$(date +%Y%m%d).sql
gzip backup_$(date +%Y%m%d).sql

Automated Backups

RDS automatically creates daily backups. Configure retention period in RDS Console (recommended: 7 days).

License

Proprietary. All rights reserved.

Support

For issues, questions, or contributions, please contact the development team or open an issue in the repository.

---

Built with modern web technologies for comprehensive content creator analytics.