Skip to content

Admin Interface

Jump to bottom
Jordan edited this page Aug 17, 2026 · 4 revisions

Admin Interface

Preserved Qoder snapshot. This deep-dive page is retained so the earlier Wiki work and its source trail are not lost. For the reconciled implementation, Architecture Overview is canonical; references below to retired controllers, listeners, services, tables, or API shapes are historical.

**Referenced Files in This Document** - [Dashboard.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Pages/Dashboard.php) - [NodeMonitoring.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Pages/NodeMonitoring.php) - [SetupWizard.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Pages/SetupWizard.php) - [AuditLogPage.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Pages/AuditLogPage.php) - [ReservationResource.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Resources/ReservationResource.php) - [AlertConfigResource.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Resources/AlertConfigResource.php) - [dashboard.blade.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/resources/views/admin/dashboard.blade.php) - [node-monitoring.blade.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/resources/views/admin/node-monitoring.blade.php) - [setup-wizard.blade.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/resources/views/admin/setup-wizard.blade.php) - [audit-log.blade.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/resources/views/admin/audit-log.blade.php) - [ResourceCalculationService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ResourceCalculationService.php) - [ReservationService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ReservationService.php) - [AuditLogService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/AuditLogService.php) - [ResourceReservation.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Models/ResourceReservation.php) - [AuditLog.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Models/AuditLog.php) - [ResourceReservationPolicy.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Policies/ResourceReservationPolicy.php) - [EnsureUserIsAdmin.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Http/Middleware/EnsureUserIsAdmin.php)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document describes the Filament 4-based administrative interface for the Dynamic Pterodactyl extension. It covers:

  • Dashboard with system health overview and capacity metrics
  • Node monitoring for real-time utilization tracking
  • Setup wizard for initial configuration of dynamic slider options
  • Audit log viewer for administrative action tracking
  • Reservation management resource for manual intervention
  • Alert configuration CRUD operations

It also provides user workflows, permission requirements, customization guidance, styling approaches, and integration points with underlying services.

Project Structure

The admin interface is composed of Filament pages and resources backed by Blade views and services that integrate with Pterodactyl and internal domain logic.

graph TB
subgraph "Filament Pages"
D["Dashboard"]
NM["Node Monitoring"]
SW["Setup Wizard"]
AL["Audit Log"]
end
subgraph "Filament Resources"
RR["Reservation Resource"]
AR["Alert Config Resource"]
end
subgraph "Views"
V_D["dashboard.blade.php"]
V_NM["node-monitoring.blade.php"]
V_SW["setup-wizard.blade.php"]
V_AL["audit-log.blade.php"]
end
subgraph "Services"
RCS["ResourceCalculationService"]
RS["ReservationService"]
ALS["AuditLogService"]
end
D --> V_D
NM --> V_NM
SW --> V_SW
AL --> V_AL
RR --> RS
AR --> RCS
D --> RCS
NM --> RCS
SW --> RCS
AL --> ALS
Loading

Diagram sources

Section sources

Core Components

  • Dashboard page: Displays connection status, key stats (products with sliders, pending reservations, revenue, conversion), and per-location capacity with health indicators.
  • Node monitoring page: Shows node-level utilization (memory/disk), server counts, maintenance state, and reserved capacity.
  • Setup wizard: Multi-tab form to configure dynamic slider options per product (pricing model, slider ranges, rates/tiers, included resources, overage rates, allowed locations).
  • Audit log page: Lists audit entries with filters and shows recent alert delivery failures.
  • Reservation resource: Read-only list of reservations with actions to extend or cancel pending ones; includes cleanup tool.
  • Alert config resource: Create/edit/delete alert configurations with thresholds, notification channels, cooldowns, and test send.

Section sources

Architecture Overview

The admin UI renders data via Filament pages/resources which call services. Services interact with Pterodactyl API and internal databases. Policies enforce permissions on sensitive actions.

sequenceDiagram
participant Admin as "Admin Browser"
participant Page as "Filament Page/Resource"
participant Service as "Domain Service"
participant Ptero as "Pterodactyl API"
participant DB as "Database"
Admin->>Page : Load Dashboard / Nodes / Alerts / Reservations
Page->>Service : buildClusterSnapshot() / getStatistics() / queryAll()
Service->>Ptero : GET nodes/locations/servers (real-time)
Ptero-->>Service : JSON payload
Service->>DB : Sum pending reservations / read configs
DB-->>Service : Aggregates
Service-->>Page : Snapshot / Stats / Records
Page-->>Admin : Rendered Filament view
Loading

Diagram sources

Detailed Component Analysis

Dashboard

  • Purpose: Provide a high-level health and capacity overview across locations.
  • Data sources:
    • Connection status via service method that tests Pterodactyl connectivity.
    • Location capacity derived from cluster snapshot aggregated per location.
    • Business stats via reservation statistics.
  • Health calculation: Based on memory utilization thresholds (warning at 80%, critical at 95%).
  • View rendering: Uses Blade sections and progress bars to visualize memory and disk usage per location.
flowchart TD
Start(["Load Dashboard"]) --> Conn["Test Pterodactyl Connection"]
Conn --> |Success| Snap["Build Cluster Snapshot"]
Conn --> |Failure| ShowErr["Show Connection Error Banner"]
Snap --> Locs["Aggregate by Location"]
Locs --> Health["Compute Health per Location"]
Health --> Stats["Fetch Reservation Stats"]
Stats --> Render["Render Blade View"]
ShowErr --> Render
Loading

Diagram sources

Section sources

Node Monitoring

  • Purpose: Real-time view of node utilization and availability per location.
  • Data flow: Fetches cluster snapshot and maps node availability details including utilization percentages and reserved capacity.
  • View features: Tables with status badges, progress bars for memory/disk, and server counts.
sequenceDiagram
participant Admin as "Admin"
participant NM as "NodeMonitoring Page"
participant RCS as "ResourceCalculationService"
participant Ptero as "Pterodactyl API"
participant DB as "Database"
Admin->>NM : Visit Node Monitoring
NM->>RCS : buildClusterSnapshot()
RCS->>Ptero : Fetch nodes + servers (paginated)
Ptero-->>RCS : Node/server data
RCS->>DB : Sum pending reservations per node
DB-->>RCS : Reserved resources
RCS-->>NM : Locations with node_availability
NM-->>Admin : Render table with utilization
Loading

Diagram sources

Section sources

Setup Wizard

  • Purpose: Configure dynamic slider options for a selected product, including pricing models and allowed locations.
  • Tabs:
    • Product selection with existing option detection and overwrite warning.
    • Sliders: Enable/disable and configure min/max/step/default for memory, CPU, disk.
    • Pricing: Linear rates, tiered tiers, or base+addon with included resources and overage rates.
    • Locations: Select allowed Pterodactyl locations.
  • Actions: Creates or updates config options via service; validates and surfaces errors as notifications.
flowchart TD
A["Select Product"] --> B{"Existing Options?"}
B --> |Yes| W["Show Overwrite Warning"]
B --> |No| C["Configure Sliders"]
W --> C
C --> D["Set Pricing Model & Rates/Tiers"]
D --> E["Choose Allowed Locations"]
E --> F["Submit: Create/Update Config Options"]
F --> G{"Validation OK?"}
G --> |No| H["Show Error Notification"]
G --> |Yes| I["Success Notification & Reset Form"]
Loading

Diagram sources

Section sources

Audit Log Viewer

  • Purpose: Track administrative actions and display recent alert delivery failures.
  • Features: Filterable table by action and entity type; section showing last 50 failed alert deliveries with trigger types and error messages.
classDiagram
class AuditLog {
+int id
+string action
+string entity_type
+int entity_id
+string entity_name
+array old_values
+array new_values
+datetime created_at
}
class AuditLogPage {
+table(Table)
+getDeliveryFailures() Collection
}
AuditLogPage --> AuditLog : "queries"
Loading

Diagram sources

Section sources

Reservation Management Resource

  • Purpose: Manual intervention for pending reservations (extend TTL, cancel) and bulk cleanup of expired ones.
  • Behavior:
    • List view with status badges, resource summary, price, expiry warnings.
    • Extend action adds minutes to pending reservations.
    • Cancel action marks pending reservations as cancelled with reason.
    • Cleanup action marks all expired pending reservations as expired.
  • Permissions: Enforced via policy when actor is provided; admin panel access bypasses restrictions.
sequenceDiagram
participant Admin as "Admin"
participant RR as "ReservationResource"
participant RS as "ReservationService"
participant DB as "Database"
Admin->>RR : Click Extend/Cancel/Cleanup
RR->>RS : extend(token, minutes, actor)
RS->>DB : Update expires_at where token/status
DB-->>RS : Rows affected
RS-->>RR : Result
RR-->>Admin : Success message + refresh
Admin->>RR : Click Cleanup
RR->>RS : cleanupExpired()
RS->>DB : Mark expired pending reservations
DB-->>RS : Count updated
RS-->>RR : Count
RR-->>Admin : Confirmation
Loading

Diagram sources

Section sources

Alert Configuration CRUD

  • Purpose: Define alert rules per location or globally, set thresholds, choose notification channels, and test alerts.
  • Capabilities:
    • Create/Edit forms with toggles and inputs for thresholds, emails, webhooks, cooldown.
    • Table listing active status, thresholds, last notification time.
    • Test action sends a trial notification using configured channels.
classDiagram
class AlertConfigResource {
+form(Schema)
+table(Table)
+getLocationOptions() array
}
class AlertService {
+sendTestNotification(config)
}
AlertConfigResource --> AlertService : "uses"
Loading

Diagram sources

Section sources

Dependency Analysis

Key dependencies between admin components and services:

graph LR
Dashboard["Dashboard"] --> RCS["ResourceCalculationService"]
NodeMon["Node Monitoring"] --> RCS
Setup["Setup Wizard"] --> RCS
Audit["Audit Log"] --> ALS["AuditLogService"]
ResRes["Reservation Resource"] --> RSvc["ReservationService"]
AlertCfg["Alert Config Resource"] --> RCS
Loading

Diagram sources

Section sources

Performance Considerations

  • Real-time data: The dashboard and node monitoring fetch live data from Pterodactyl; avoid excessive polling. Use Filament’s poll feature judiciously (e.g., reservations list polls every 30 seconds).
  • Batched API calls: Cluster snapshot batches node and server queries; large clusters may incur multiple paginated requests.
  • Database locks: Reservation creation uses pessimistic locking with retries to handle deadlocks safely.
  • Degraded snapshots: When Pterodactyl is unavailable, degraded snapshots are returned to keep UI responsive.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Pterodactyl connection issues:
    • Check connection status banner on the dashboard; if failed, verify API URL and key settings.
    • Review error messages surfaced by the connection test method.
  • No locations or nodes:
    • Ensure Pterodactyl credentials are correct and accessible.
    • Verify that locations exist and are reachable.
  • Alert delivery failures:
    • Inspect the “Recent Alert Delivery Failures” section in the audit log page for failed channels and last error messages.
  • Reservation actions blocked:
    • Confirm you have admin panel access; policies allow admin bypass.
    • For non-admin actors, ensure ownership checks pass.

Section sources

Conclusion

The Filament 4 admin interface provides a comprehensive operational view of system health, node utilization, and business metrics. Administrators can configure dynamic pricing through the setup wizard, manage reservations manually, and monitor alert delivery effectiveness. Integration with Pterodactyl is real-time and resilient, while policies and middleware enforce secure access.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

User Workflows

  • Monitor system health:
    • Open Dashboard to see connection status, location health, and key metrics.
    • Navigate to Node Monitoring for detailed per-node utilization.
  • Manage reservations:
    • In Reservations, filter by status, extend pending reservations, or cancel them.
    • Use Cleanup Expired to mark overdue pending reservations as expired.
  • Configure alerts:
    • Create or edit alert configs with thresholds and channels; use Test to validate.
    • Review recent delivery failures in the Audit Log page.

[No sources needed since this section doesn't analyze specific files]

Permission Requirements

  • Admin panel access: Required for most admin pages and resources; enforced via policy before hooks and middleware for API endpoints.
  • Reservation actions:
    • Admins can perform any action.
    • Non-admin users must own the reservation to cancel or extend.

Section sources

Customization and Styling

  • Views: Blade templates under resources/views/admin/ use Filament panel components and Tailwind utility classes for consistent styling.
  • Filament 4 APIs: Pages and resources leverage Filament 4 schema and table builders for forms and listings.
  • Extensibility: Add custom columns, filters, or actions in resources; customize views with standard Blade patterns.

Section sources

Integration Points

  • Pterodactyl API:
    • Real-time fetching of locations, nodes, and servers; pagination handled internally.
    • Connection testing and degraded fallback behavior.
  • Internal services:
    • ReservationService manages lifecycle and statistics.
    • AuditLogService records administrative actions.
  • Models:
    • ResourceReservation and AuditLog define storage structures and relationships.

Section sources

DynamicPterodactyl · Dynamic Resource Sliders for Paymenter × Pterodactyl · Reviewed code checkpoint · Publication commits intentionally pin their latest code-bearing predecessor because a Git commit cannot self-reference its unknown object ID.

DynamicPterodactyl

Guides

Architecture

Core Services

API Reference

Database

System

Clone this wiki locally