Karbon

Karbon - A Laravel & Filament application for tracking and analyzing website environmental impact, accessibility, performance, and SEO metrics.

Features

• Project Management - Manage website projects with analytics integration
• URL Tracking - Import URLs from sitemap.xml and track metrics
• Action Analysis - Run and store analysis results for:
  • Carbon footprint analysis
  • Accessibility checks
  • Performance testing
  • SEO analysis
• API Integration - Submit analysis results via versioned REST API
• Analytics Dashboard - Built with Filament PHP for beautiful admin interface

Getting started

If you're using DDEV for local development, prefix commands with ddev:

# Start ddev
ddev start
ddev composer install
cp .env.example .env

# Generate application key
ddev php artisan key:generate

# Run migrations
ddev php artisan migrate

# Fresh migration with seeding
ddev php artisan migrate:fresh --seed

# Import sitemap
ddev php artisan sitemap:import statik.be

Database Seeders

The application includes the following seeders:

• DatabaseSeeder - Creates a default user ([email protected] / admin)
• ProjectSeeder - Creates a sample project for statik.be

Default Login Credentials:

• Email: [email protected]
• Password: admin

To run all seeders:

php artisan db:seed

To run a specific seeder:

php artisan db:seed --class=ProjectSeeder

Artisan Commands

Import Sitemap

Import URLs from a project's sitemap.xml into the database.

# Import sitemap by domain (auto-detects sitemap location)
php artisan sitemap:import statik.be

# Import sitemap with custom URL
php artisan sitemap:import statik.be --url=https://statik.be/custom-sitemap.xml

The command will:

• Find the project by domain name
• Automatically detect sitemap location or use custom URL
• Handle sitemap index files (sitemaps that reference other sitemaps)
• Show progress bars for large sitemaps
• Skip duplicate URLs
• Display summary statistics

API Statistics Tracking

The application tracks API usage statistics in real-time using Redis, then snapshots them daily to the database for permanent storage.

Architecture:

• Real-time tracking: Redis counters track API hits during the day
• Daily snapshot: Scheduled command runs at 00:05 to save stats to database and JSON
• Permanent storage: Stats stored in api_url_stats database table
• Auto-cleanup: Redis keys cleaned up after successful snapshot

What's tracked:

• Total API requests per day
• Cache hit/miss ratios
• HTTP status code breakdown
• Per-URL request counts
• Per-project request counts
• URL metadata (project association, timestamps)

Console Commands:

# Snapshot yesterday's API hits from Redis to database (runs automatically at 00:05)
php artisan api:snapshot-hits

# Snapshot a specific date
php artisan api:snapshot-hits 2025-10-26

The snapshot command will:

• Fetch all API statistics from Redis for the specified date
• Store per-URL statistics in the api_url_stats database table
• Clean up Redis keys after successful snapshot
• Display a summary of requests, cache hits, and unique URLs/projects

Tracked Metrics:

• api:hits:{date}:total - Total requests
• api:hits:{date}:cache_hit - Cached responses
• api:hits:{date}:cache_miss - Non-cached responses
• api:hits:{date}:status:{code} - HTTP status code breakdown
• api:hits:{date}:url:{hash} - Per-URL counters
• api:hits:{date}:project:{id} - Per-project counters

Database Schema: The api_url_stats table stores:

• URL and SHA256 hash for efficient lookups
• Associated project ID
• Daily hit statistics (JSON column with date-keyed data)
• Total hits across all dates
• First and last tracked timestamps

Running Checks

Create check batches for projects to analyze URLs:

# Create batches for all projects (all enabled check types)
php artisan checks:run-all

# Preview what would be created without actually creating
php artisan checks:run-all --dry-run

# Run checks for specific project
php artisan checks:run-all --project=statik.be

# Run specific check type across all projects
php artisan checks:run-all --type=carbon

# Combine filters
php artisan checks:run-all --project=statik.be --type=carbon

Backup Commands

The application uses Spatie Laravel Backup for automated backups:

# Run full backup (database + files)
php artisan backup:run

# Backup only database
php artisan backup:run --only-db

# Backup only files
php artisan backup:run --only-files

# List all backups
php artisan backup:list

# Clean old backups
php artisan backup:clean

# Monitor backup health
php artisan backup:monitor

Production Deployment

The application uses GitHub Actions for automated deployment with Docker.

How It Works

1. Push to develop branch (or trigger manually)
2. GitHub Actions builds assets and creates .env.production from secrets
3. Rsyncs files to your server via SSH
4. Rebuilds Docker containers, runs migrations, clears caches
5. Health checks verify deployment success

Getting Started

1. Set up your server - Install Docker and create app directory
2. Configure GitHub Secrets - Add SSH keys, database passwords, etc.
3. Run first deployment - Manual trigger from GitHub Actions
4. Automatic deployments - Every push to develop deploys automatically

Documentation

• DEPLOYMENT-SETUP.md - Complete deployment setup guide
• GITHUB-SECRETS.md - Required GitHub secrets configuration
• Makefile - Production management commands (make help)
• CLAUDE.md - Full project documentation for development

Docker Stack

• Alpine 3.21 + Caddy web server + PHP 8.4
• MySQL 8.0 database
• Redis 7 for cache and queues
• Supervisor manages queue workers and scheduler

Production Commands (on server)

make ps           # View container status
make logs-app     # View application logs
make health       # Check service health
make backup       # Create backup
make restart      # Restart services
make help         # See all commands

Tech Stack

• Laravel 12 - PHP framework
• Filament v4 - Admin panel
• MySQL 8.0 - Database
• Redis 7 - Cache & queue backend
• Vite - Frontend build tool
• Tailwind CSS v4 - Styling

Key Packages

• Filament Packages:

  • filament/filament - Core admin panel
  • bezhansalleh/filament-shield - Role-based permissions
  • leandrocfe/filament-apex-charts - Chart widgets
  • dutchcodingcompany/filament-socialite - OAuth authentication
  • filament/spatie-laravel-settings-plugin - Settings management

• Laravel Packages:

  • spatie/laravel-backup - Automated backups
  • spatie/laravel-permission - Roles & permissions
  • laravel/socialite - OAuth integration

Development

For detailed development documentation, see CLAUDE.md.

License

MIT