Architecture¶

The core-developer package provides administrative developer tools for the Host UK platform. It is designed exclusively for "Hades" tier users (god-mode access) and includes debugging, monitoring, and server management capabilities.

Package Overview¶

Directory Structure¶

src/
├── Boot.php                    # Service provider & event handlers
├── Controllers/
│   └── DevController.php       # REST API endpoints
├── Concerns/
│   └── RemoteServerManager.php # SSH connection trait
├── Console/Commands/
│   └── CopyDeviceFrames.php    # Asset management command
├── Data/
│   └── RouteTestResult.php     # DTO for route test results
├── Exceptions/
│   └── SshConnectionException.php
├── Lang/
│   └── en_GB/developer.php     # Translations
├── Listeners/
│   └── SetHadesCookie.php      # Login event listener
├── Middleware/
│   ├── ApplyIconSettings.php   # Icon preferences from cookies
│   └── RequireHades.php        # Authorization middleware
├── Migrations/
│   └── 0001_01_01_000001_create_developer_tables.php
├── Models/
│   └── Server.php              # SSH server model
├── Providers/
│   ├── HorizonServiceProvider.php
│   └── TelescopeServiceProvider.php
├── Routes/
│   └── admin.php               # Route definitions
├── Services/
│   ├── LogReaderService.php    # Log file parsing
│   └── RouteTestService.php    # Route testing logic
├── Tests/
│   └── UseCase/
│       └── DevToolsBasic.php   # Feature tests
└── View/
    ├── Blade/
    │   └── admin/              # Blade templates
    │       ├── activity-log.blade.php
    │       ├── cache.blade.php
    │       ├── database.blade.php
    │       ├── logs.blade.php
    │       ├── route-inspector.blade.php
    │       ├── routes.blade.php
    │       └── servers.blade.php
    └── Modal/
        └── Admin/              # Livewire components
            ├── ActivityLog.php
            ├── Cache.php
            ├── Database.php
            ├── Logs.php
            ├── RouteInspector.php
            ├── Routes.php
            └── Servers.php

Event-Driven Module Loading¶

The module uses the Core Framework's event-driven lazy loading pattern. The Boot class declares which events it listens to:

public static array $listens = [
    AdminPanelBooting::class => 'onAdminPanel',
    ConsoleBooting::class => 'onConsole',
];

This ensures routes, views, and commands are only registered when the admin panel or console is actually used.

Lifecycle Events¶

Core Components¶

1. Livewire Admin Pages¶

All admin pages are full-page Livewire components using attribute-based configuration:

#[Title('Application Logs')]
#[Layout('hub::admin.layouts.app')]
class Logs extends Component

Each component: - Checks Hades access in mount() - Uses developer::admin.{name} view namespace - Has corresponding Blade template in View/Blade/admin/

2. API Controller¶

DevController provides REST endpoints for: - /hub/api/dev/logs - Recent log entries - /hub/api/dev/routes - Route listing - /hub/api/dev/session - Session/request info - /hub/api/dev/clear/{type} - Cache clearing

All endpoints are protected by RequireHades middleware and rate limiting.

3. Services¶

LogReaderService - Memory-efficient log reading (reads from end of file) - Parses Laravel log format - Automatic sensitive data redaction - Multi-log file support (daily/single channels)

RouteTestService - Route discovery and formatting - Request building with parameters - In-process request execution - Response formatting and metrics

4. RemoteServerManager Trait¶

Provides SSH connection management for classes that need remote server access:

class DeployApplication implements ShouldQueue
{
    use RemoteServerManager;

    public function handle(): void
    {
        $this->withConnection($this->server, function () {
            $this->run('cd /var/www && git pull');
        });
    }
}

Key methods: - connect() / disconnect() - Connection lifecycle - withConnection() - Guaranteed cleanup pattern - run() / runMany() - Command execution - fileExists() / readFile() / writeFile() - File operations - getDiskUsage() / getMemoryUsage() - Server stats

Data Flow¶

Admin Page Request¶

Browser Request
    ↓
Laravel Router → /hub/dev/logs
    ↓
Livewire Component (Logs.php)
    ↓
mount() → checkHadesAccess()
    ↓
loadLogs() → LogReaderService
    ↓
render() → developer::admin.logs
    ↓
Response (HTML)

API Request¶

Browser/JS Request
    ↓
Laravel Router → /hub/api/dev/logs
    ↓
RequireHades Middleware
    ↓
Rate Limiter (throttle:dev-logs)
    ↓
DevController::logs()
    ↓
LogReaderService
    ↓
Response (JSON)

SSH Connection¶

Servers Component
    ↓
testConnection($serverId)
    ↓
Server::findOrFail()
    ↓
Write temp key file
    ↓
Process::run(['ssh', ...])
    ↓
Parse result
    ↓
Update server status
    ↓
Clean up temp file

Database Schema¶

servers table¶

Indexes: - workspace_id - (workspace_id, status) composite

Admin Menu Structure¶

The module registers a "Dev Tools" menu group with these items:

Dev Tools (admin group, priority 80)
├── Logs        → /hub/dev/logs
├── Activity    → /hub/dev/activity
├── Servers     → /hub/dev/servers
├── Database    → /hub/dev/database
├── Routes      → /hub/dev/routes
├── Route Inspector → /hub/dev/route-inspector
└── Cache       → /hub/dev/cache

The menu is only visible to users with admin flag (Hades tier).

Rate Limiting¶

API endpoints have rate limits configured in Boot::configureRateLimiting():

Rate limits are per-user (or per-IP for unauthenticated requests).

Third-Party Integrations¶

Laravel Telescope¶

Custom TelescopeServiceProvider configures: - Gate for Hades-only access in production - Entry filtering (errors, failed jobs in production) - Sensitive header/parameter hiding

Laravel Horizon¶

Custom HorizonServiceProvider configures: - Gate for Hades-only access - Notification routing from config (email, SMS, Slack)

Laravel Pulse¶

Custom Pulse dashboard view override at View/Blade/vendor/pulse/dashboard.blade.php.

Configuration¶

The module expects these config keys (should be in config/developer.php):

return [
    // Hades cookie token
    'hades_token' => env('HADES_TOKEN'),

    // SSH settings
    'ssh' => [
        'connection_timeout' => 30,
        'command_timeout' => 60,
    ],

    // Horizon notifications
    'horizon' => [
        'mail_to' => env('HORIZON_MAIL_TO'),
        'sms_to' => env('HORIZON_SMS_TO'),
        'slack_webhook' => env('HORIZON_SLACK_WEBHOOK'),
        'slack_channel' => env('HORIZON_SLACK_CHANNEL', '#alerts'),
    ],
];

Extension Points¶

Adding New Admin Pages¶

1. Create Livewire component in View/Modal/Admin/
2. Create Blade view in View/Blade/admin/
3. Add route in Routes/admin.php
4. Add menu item in Boot::adminMenuItems()
5. Add translations in Lang/en_GB/developer.php

Adding New API Endpoints¶

1. Add method to DevController
2. Add route in Routes/admin.php API group
3. Create rate limiter in Boot::configureRateLimiting()
4. Apply throttle:limiter-name middleware

Using RemoteServerManager¶

use Core\Developer\Concerns\RemoteServerManager;

class MyJob
{
    use RemoteServerManager;

    public function handle(Server $server): void
    {
        $this->withConnection($server, function () {
            // Commands executed on remote server
            $result = $this->run('whoami');
            // ...
        });
    }
}

Performance Considerations¶

1. Log Reading - Uses backwards reading to avoid loading entire log into memory. Configurable maxBytes limit.

2. Route Caching - Routes are computed once per request. The RouteInspector uses #[Computed(cache: true)] for route list.

3. Query Log - Enabled only in local environment (Boot::boot()).

4. SSH Connections - Always disconnect via withConnection() pattern to prevent resource leaks.

Dependencies¶

Composer Requirements¶

• host-uk/core - Core framework
• host-uk/core-admin - Admin panel infrastructure
• phpseclib3 - SSH connections (via RemoteServerManager)
• spatie/laravel-activitylog - Activity logging

Frontend Dependencies¶

• Flux UI components
• Tailwind CSS
• Livewire 3.x

Testing Strategy¶

Tests use Pest syntax and focus on: - Page rendering and content - Authorization enforcement - API endpoint behaviour - Service logic

Test database: SQLite in-memory with Telescope/Pulse disabled.