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

Aspect	Detail
Namespace	`Core\Developer\`
Type	L1 Module (Laravel Package)
Dependencies	`host-uk/core`, `host-uk/core-admin`
PHP Version	8.2+
Laravel Version	11.x / 12.x
Livewire Version	3.x / 4.x

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:

php

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

Event	Handler	What Happens
`AdminPanelBooting`	`onAdminPanel()`	Registers views, routes, Pulse override
`ConsoleBooting`	`onConsole()`	Registers Artisan commands

Core Components

1. Livewire Admin Pages

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

php

#[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:

php

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

Column	Type	Description
id	bigint	Primary key
workspace_id	bigint	FK to workspaces
name	varchar(128)	Display name
ip	varchar(45)	IPv4/IPv6 address
port	smallint	SSH port (default 22)
user	varchar(64)	SSH username
private_key	text	Encrypted SSH key
status	varchar(32)	pending/connected/failed
last_connected_at	timestamp	Last successful connection
timestamps		created_at, updated_at
soft_deletes		deleted_at

Indexes:

workspace_id
(workspace_id, status) composite

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():

Limiter	Limit	Purpose
`dev-cache-clear`	10/min	Prevent rapid cache clears
`dev-logs`	30/min	Log reading
`dev-routes`	30/min	Route listing
`dev-session`	60/min	Session info

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):

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

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

Adding New API Endpoints

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

Using RemoteServerManager

php

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

Log Reading - Uses backwards reading to avoid loading entire log into memory. Configurable maxBytes limit.
Route Caching - Routes are computed once per request. The RouteInspector uses #[Computed(cache: true)] for route list.
Query Log - Enabled only in local environment (Boot::boot()).
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.

Architecture ​

Package Overview ​

Directory Structure ​

Event-Driven Module Loading ​

Lifecycle Events ​

Core Components ​

1. Livewire Admin Pages ​

2. API Controller ​

3. Services ​

4. RemoteServerManager Trait ​

Data Flow ​

Admin Page Request ​

API Request ​

SSH Connection ​

Database Schema ​

servers table ​

Admin Menu Structure ​

Rate Limiting ​

Third-Party Integrations ​

Laravel Telescope ​

Laravel Horizon ​

Laravel Pulse ​

Configuration ​

Extension Points ​

Adding New Admin Pages ​

Adding New API Endpoints ​

Using RemoteServerManager ​

Performance Considerations ​

Dependencies ​

Composer Requirements ​

Frontend Dependencies ​

Testing Strategy ​