Skip to content

Getting Started

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

Getting Started

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, or API shapes are historical.

Current Setup Path

Install the DynamicPterodactyl extension and its matching Paymenter companion as one reviewed release. Run migrations before booting the extension, configure the panel URL and application key, define per-node capacity policies, confirm exclusive provisioning control, and use the setup wizard to create native Paymenter dynamic-slider options. Do not deploy either side independently.

Use the product resource-quote endpoint for checkout previews; reservations are created by Paymenter cart events, not by a public reservation API.

Architecture Overview

**Referenced Files in This Document** - [DynamicPterodactyl.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/DynamicPterodactyl.php) - [routes/api.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/routes/api.php) - [Admin/Pages/SetupWizard.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Admin/Pages/SetupWizard.php) - [Services/ConfigOptionSetupService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ConfigOptionSetupService.php) - [Services/SliderConfigReaderService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/SliderConfigReaderService.php) - [Listeners/CartItemCreatedListener.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Listeners/CartItemCreatedListener.php) - [Http/Controllers/Api/AvailabilityController.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Http/Controllers/Api/AvailabilityController.php) - [Services/ReservationService.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Services/ReservationService.php) - [Models/ResourceReservation.php](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/Models/ResourceReservation.php) - [AGENTS.md](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/AGENTS.md) - [DECISIONS.md](https://github.com/ObsidianNetwork/dynamic-pterodactyl/blob/6b7f83bda6f7c3fe014d52428b31af1638daa6cc/DECISIONS.md)

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 extension is a companion to Paymenter’s built-in Pterodactyl server extension. It adds dynamic resource sliders (RAM, CPU, Disk) to your Pterodactyl products and provides real-time availability checks with short-lived reservations during checkout. The reservation TTL is configurable but defaults to 15 minutes. Pricing for the sliders is handled by Paymenter core; this extension focuses on reading slider configuration metadata, checking live availability against Pterodactyl, and managing reservations.

Key behaviors:

  • Real-time availability queries to Pterodactyl (no caching).
  • Short-lived reservations to prevent overselling during checkout.
  • Admin setup wizard to create dynamic slider options per product.
  • Customer-facing endpoints return only aggregate capacity per location; node-level details are admin-only.

Section sources

Project Structure

The extension lives under Paymenter as an “Other” extension and integrates via its boot process. It registers routes, policies, listeners, and scheduled tasks that tie into Paymenter’s cart and invoice lifecycle.

graph TB
A["DynamicPterodactyl::boot()"] --> B["Register routes<br/>api/dynamic-pterodactyl/*"]
A --> C["Register policy<br/>ResourceReservationPolicy"]
A --> D["Register views namespace"]
A --> E["Event listeners<br/>CartItemCreated / CartItemDeleted / InvoicePaid / ServiceCreated"]
A --> F["Scheduled jobs<br/>cleanup expired reservations every minute<br/>check capacity alerts every 5 minutes"]
Loading

Diagram sources

Section sources

Core Components

  • Extension entrypoint: loads routes, policies, observers, event listeners, and schedules.
  • Setup Wizard: creates dynamic_slider ConfigOptions for memory, CPU, disk, plus optional location selector.
  • Slider config reader: exposes slider limits and pricing metadata to frontend/API.
  • Availability API: returns per-location maximum allocatable resources based on live Pterodactyl data.
  • Reservation service: manages creation, confirmation, cancellation, extension, and cleanup of reservations with pessimistic locking and idempotency.
  • Listeners: bridge Paymenter events (cart/invoice/service) into reservation actions.

Section sources

Architecture Overview

This extension complements the built-in Pterodactyl server extension. It does not provision servers itself; it ensures resources are available and reserved while customers complete checkout.

sequenceDiagram
participant Client as "Customer"
participant Paymenter as "Paymenter Core"
participant Ext as "Dynamic Pterodactyl"
participant Ptero as "Pterodactyl API"
Client->>Paymenter : Add product with dynamic sliders to cart
Paymenter->>Ext : Event CartItemCreated
Ext->>Ptero : Read live availability (batched)
Ptero-->>Ext : Node capacity snapshot
Ext->>Ext : Select best-fit node
Ext->>Ext : Create reservation (pending, TTL=15 min)
Ext-->>Paymenter : Store token in checkout_config
Client->>Paymenter : Complete payment
Paymenter->>Ext : Event InvoicePaid
Ext->>Ext : Confirm reservation (pending -> confirmed)
Ext-->>Paymenter : Link reservation to service
Loading

Diagram sources

Detailed Component Analysis

Installation and Configuration

  • Install the extension within Paymenter as an “Other” extension. On install, migrations run automatically to create reservation and related tables.
  • Configure extension settings:
    • Pterodactyl Panel URL
    • Pterodactyl Application API Key
    • Reservation TTL (minutes), default 15

These settings are exposed through the extension’s configuration UI and used by services to connect to Pterodactyl and manage reservation lifetimes.

Section sources

Initial Setup: Creating Dynamic Sliders

Use the Filament-based Setup Wizard to add RAM, CPU, and Disk sliders to a product:

  • Choose pricing model (linear, tiered, base_addon) and rates.
  • Enable/disable each slider and set min/max/step/default values.
  • Optionally add a Location selector to choose where the server will be provisioned.

The wizard writes native dynamic_slider ConfigOptions to Paymenter core. These options drive both the frontend sliders and pricing calculations.

Section sources

Quick Start: Verify the Extension Is Working

  • Ensure Pterodactyl credentials are configured in the extension settings.
  • Run the Setup Wizard for a product to enable sliders.
  • Visit the product page and confirm sliders appear with correct ranges.
  • Check availability endpoint for a location to see max allocatable resources.
  • Add the product to cart; a pending reservation should be created and stored in checkout_config.
  • Complete payment; the reservation should transition to confirmed and link to the new service.

Relevant endpoints:

  • GET /api/dynamic-pterodactyl/availability/{locationId}
  • POST /api/dynamic-pterodactyl/reservation
  • GET /api/dynamic-pterodactyl/pricing/config/{productId}

Section sources

How Reservations Work

  • Creation: When a cart item with dynamic sliders is added, the extension reads slider values, selects a best-fit node from live availability, and creates a pending reservation with a TTL.
  • Confirmation: After successful payment, the reservation is confirmed and linked to the service.
  • Expiration: Pending reservations past their TTL are marked expired by a scheduled job running every minute.
  • Cancellation: Reservations can be cancelled (e.g., cart removal or admin action).
flowchart TD
Start(["Cart Item Created"]) --> CheckSliders{"Has dynamic_slider options?"}
CheckSliders --> |No| EndNo["Skip reservation"]
CheckSliders --> |Yes| FetchAvail["Read live availability"]
FetchAvail --> SelectNode["Select best-fit node"]
SelectNode --> CreateRes["Create reservation (pending, TTL)"]
CreateRes --> StoreToken["Store token in checkout_config"]
StoreToken --> WaitPay["Await payment"]
WaitPay --> Paid{"Invoice paid?"}
Paid --> |Yes| Confirm["Confirm reservation (pending -> confirmed)"]
Paid --> |No| Expire["TTL expires -> mark expired"]
Confirm --> EndOk["Linked to service"]
Expire --> EndExpired["Released back to pool"]
Loading

Diagram sources

Section sources

Relationship to Paymenter’s Built-in Pterodactyl Server Extension

  • This extension is a companion enhancement. It handles dynamic sliders, availability, and reservations.
  • The built-in Pterodactyl server extension remains responsible for actual server provisioning.
  • If this extension fails, the product still works without sliders (graceful degradation).

Section sources

Dependency Analysis

graph LR
Boot["DynamicPterodactyl::boot()"] --> Routes["routes/api.php"]
Boot --> Policy["ResourceReservationPolicy"]
Boot --> Views["views namespace"]
Boot --> Listeners["CartItemCreated / Deleted, InvoicePaid, ServiceCreated"]
Listeners --> ResSvc["ReservationService"]
ResSvc --> NodeSel["NodeSelectionService"]
AvailCtrl["AvailabilityController"] --> ResCalc["ResourceCalculationService"]
AvailCtrl --> NodeSel
SetupWizard["SetupWizard"] --> OptSetup["ConfigOptionSetupService"]
SliderCfg["SliderConfigReaderService"] --> ConfigOpt["ConfigOption (dynamic_slider)"]
Loading

Diagram sources

Section sources

Performance Considerations

  • Real-time availability: Pterodactyl API responses are never cached; availability is always fresh. Batch calls are used to reduce overhead.
  • Rate limiting: Customer endpoints are throttled to protect the Pterodactyl API budget.
  • Reservation locking: Uses pessimistic DB locks with deadlock retries to ensure correctness under concurrency.
  • Scheduled cleanup: Runs every minute to expire old reservations promptly.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common setup issues and resolutions:

  • Missing Pterodactyl credentials: Ensure the panel URL and an application API key with Locations, Nodes, and Servers read access are set in extension settings. Without all three permissions, availability checks and reservations cannot succeed.
  • No sliders appearing: Use the Setup Wizard to create dynamic_slider options for the product. Verify the product has at least one slider enabled.
  • Availability shows zero capacity: Confirm Pterodactyl nodes have headroom for the requested resources. Check the availability endpoint for the selected location.
  • Reservation not created on cart add: Ensure the product has dynamic_slider options and a location is selected. Errors are logged but do not block cart operations.
  • Reservation expired before payment: Increase the reservation TTL if checkout takes longer than the default 15 minutes.
  • Admin cannot see node details: Node-level capacity is admin-only; customer endpoints return only aggregate maxima.

Where to look:

  • Extension settings: Pterodactyl URL, API key, reservation TTL.
  • Setup Wizard: Create/update slider options per product.
  • Availability endpoint: Validate per-location capacity.
  • Reservation service: Inspect state transitions and TTL behavior.
  • Logs: Listener errors when creating reservations.

Section sources

Conclusion

The Dynamic Pterodactyl extension enhances your Pterodactyl products with dynamic RAM/CPU/Disk sliders, real-time availability checks, and short-lived reservations to prevent overselling during checkout. It integrates seamlessly with Paymenter’s built-in Pterodactyl server extension, leaving provisioning to the core while focusing on availability and reservation management. Use the Setup Wizard to configure sliders, verify availability via the API, and rely on automatic reservation lifecycle handling during the cart-to-payment flow.

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

Appendices

API Surface Summary

  • Availability and pricing (throttled):
    • GET /api/dynamic-pterodactyl/availability/{locationId}
    • POST /api/dynamic-pterodactyl/pricing/calculate
    • GET /api/dynamic-pterodactyl/pricing/config/{productId}
  • Reservations (checkout flow, throttled):
    • POST /api/dynamic-pterodactyl/reservation
    • GET /api/dynamic-pterodactyl/reservation/{token}
    • DELETE /api/dynamic-pterodactyl/reservation/{token}
    • POST /api/dynamic-pterodactyl/reservation/{token}/extend
  • Admin (session-authenticated, throttled):
    • GET /api/dynamic-pterodactyl/admin/reservations
    • POST /api/dynamic-pterodactyl/admin/reservations/{token}/cancel
    • GET /api/dynamic-pterodactyl/admin/capacity
    • GET /api/dynamic-pterodactyl/admin/availability/{locationId}/nodes

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