Backend Administration Platform (admin-alta.alta-voce.tech)

Auto-generated Documentation Links

API REST Documentation (Scribe) : View API Documentation - Automatically generated OpenAPI/Postman docs.

1. Architectural Role & Specifications

The admin-alta backend serves as the core orchestration and control tower for the entire Alta Voce ecosystem. Built on Laravel 10 / PHP 8.1, it handles three critical systems:

1. High-Frequency Telemetry Ingestion: A REST API entry point that receives diagnostic payloads from desktop clients, sanitizes inputs, and applies optimization filters (reducing JSON payload storage footprint by 96%).
2. Filament Admin Dashboard (v3): A secure Livewire, Alpine.js, and Tailwind CSS administrative portal designed for customer onboarding, subscription control, and system health checks.
3. Scheduled Automated Workloads (CRON / CLI): A temporal engine orchestrating nightly calculations, invoicing, data retention policies, and automated audio tuning.

2. REST API Authentication

The REST API uses Laravel Sanctum opaque tokens (not JWT). Tokens are created on login and passed as a Bearer header on all protected requests.

Token lifecycle

• Expiration: 2 hours after creation (configurable via sanctum.expiration).
• Proactive refresh: The frontend client automatically calls POST /api/refresh-token when fewer than 30 minutes remain on the current token.
• Reactive refresh: On a 401 response, the client retries refresh once if the user was active within the last 5 minutes; otherwise it forces logout.

Authentication endpoints

Password policy (account setup)

New accounts set via the invitation flow must choose a password that contains at least one uppercase letter, one lowercase letter, one digit, and one special character (minimum 8 characters). The setup link is valid for 3 days.

Role system

Three roles exist in the roles table:

Impersonation

Admin accounts can impersonate any other account:

• POST /api/impersonate — Start impersonation. Returns a new token scoped to the target account. The event is logged in the impersonations table.
• POST /api/impersonate/stop — Restore the original admin session and token.
• The frontend (ImpersonateWidget.vue) shows a persistent banner while impersonation is active and allows stopping it at any time.

3. Desktop Plugin API (/api/altacall/*)

Routes used exclusively by the AltaCall Windows desktop client. Authentication is handled by a custom AltaAuthMiddleware that supports three schemes simultaneously: PHP Basic Auth (PHP_AUTH_USER/PHP_AUTH_PW), HTTP Basic Auth (Authorization: Basic ...), and a proprietary Digest scheme (Authorization: Digest clientId:userId:sha256checksum).

All plugin routes also pass through AltacallMonitoringMiddleware, which records request metrics (duration, memory, response size, IP, license info).

Event handling

The POST /api/altacall/event endpoint dispatches each event to a typed handler:

Returns {"actions": ["config.update"]} when the client must refresh its config, {"actions": []} otherwise.

4. Filament Admin Dashboard Architecture (v3)

The dashboard is structured around Filament Resources that map to Eloquent database models. Each resource implements lists (tables), forms, filters, and custom operational actions:

4.1. ABTestsResource (A/B Test Campaign Management)

• Role: Configures and monitors voice transformation campaigns, comparing acoustical algorithms (SMA, VMO, Smile) against control groups.
• Table Columns: id, name, status (badges: active/pending/completed), start_date, end_date, goal_progress (interactive progress bar showing % of target agent hours captured).
• Form Inputs: Campaign settings (name, dates, client target group), voice enhancement preset selection (link to transfos), target segmentation by agent skill labels.
• Custom Actions:
  • Download CSV: Raw dump of all telemetries and KPIs for data science analysis.
  • Force Rotation: Instantly triggers preset rotation.

4.2. ClientResource (Tenant Account Administration)

• Role: Manages subscribed corporate clients (contact centers).
• Table Columns: name, email, email_billing, vat_number, groups_count.
• Form Inputs: Fiscal identifiers, contact details, JSON config Editor (network constraints, telemetry thresholds, alert rules).

4.3. UserResource (Caller Agents)

• Role: Manages profiles of caller agents registered via telemetry.
• Table Columns: name (Windows username), vmo_user_id (desktop UUID), last_update, status.
• Custom Actions:
  • Export Usage Trace (CSV/JSON): Daily voice usage, active presets, and median F0/Pitch histories.

4.4. AccountsResource (Portal Accounts)

• Role: Manages portal user accounts (admins and client-admins who log in to the web dashboard).
• Separate from users (which are the Alta Call agents on workstations). Portal accounts use email/password via Sanctum.

4.5. MachinesResource (Workstations Inventory & Health)

• Role: Manages active computer workstations executing the desktop application.
• Table Columns: computer (hostname), vmo_machine_id, version, local_ip_address, status (green/red based on open issues).
• Custom Actions: Diagnostics tab listing open anomalies (from machines_issues).

4.6. InvoicesResource (Automated Invoicing Engine)

• Role: Handles monthly invoice calculations and processing.
• Table Columns: invoice_number, client.name, period_start, period_end, amount_excl_tax, amount_incl_tax, status (paid/unpaid/frozen).
• Custom Actions:
  • Download PDF: Official invoice PDF from Blade template.
  • Send Email Notification: Emails the PDF download link to the billing contact.

4.7. LicenseResource (Handshake Keys Management)

• Role: Configures authentication licenses for desktop clients.
• Form Inputs: Auto-generation of cryptographically secure license tokens, fancyname label for support desk, valid toggle to revoke.

4.8. TransformationsResource (Voice Transformation Presets)

• Role: Manages voice enhancement algorithm presets (transfos table). Each preset defines the transfo_mode (SMA, VMO, MANUAL) and its parameter JSON payload injected into plugin configs.

4.9. GroupsResource & MonitoringResource

• GroupsResource: Manage tenant departments/teams. Groups link clients, users, machines, and licenses.
• MonitoringResource: Inspect the AltacallMonitoringMiddleware recorded request metrics for plugin API calls (latency, error rates, slow requests).

4.10. AltacallLogResource & PluginLogResource

• Role: Inspect and download system diagnostic log bundles and softphone integration logs sent by workstations.

4.11. SoftwareVersionResource (Release Versioning Control)

• Role: Manages desktop application build deployments, download links, and minimum required version enforcement.

4.12. RecordingsResource & SuggestionResource & ExternalUtilityResource

• RecordingsResource: Rules and files for on-demand audio recording capture, used during A/B test quality control.
• SuggestionResource: User feedback tickets submitted from the desktop client.
• ExternalUtilityResource: Companion tool/utility downloads distributed via the portal.

5. Scheduled Automated Workloads (CRON / CLI)

[!IMPORTANT] Asynchronous Execution Architecture (FastCGI) Because the application runs on Gandi Simple Hosting with strict 30-second HTTP timeouts, scheduled tasks are processed via an asynchronous mechanism:

1. An external scheduler (cron-job.org) triggers routes under /cron/* via HTTP GET.
2. The route calls fastcgi_finish_request(), returning HTTP 200 immediately to close the network connection.
3. PHP continues running in the background (set_time_limit(170)) to complete long-running aggregations.

Complete Cron Endpoints Reference

6. Telemetry Processing Pipeline

Every telemetry report received by the backend passes through a multi-stage pipeline inside TelemController@postTelemetry:

graph TD
    A[Incoming Telemetry Packet] --> B[AltaAuthMiddleware — License/Digest auth]
    B --> C{Valid auth?}
    C -- No --> X1[401 Unauthorized]
    C -- Yes --> D[Version Check against min required version]
    D --> E[Resolve Entities: User / Machine / Process]
    E --> F{Downtime Payload?}
    F -- Yes --> G[Store raw telemetry & return early]
    F -- No --> H["TelemetryCleaningService — 96% payload reduction"]
    H --> I[Process Audio Devices & Audiostream]
    I --> J[Calculate Running Process Stats]
    J --> K["Atomic DB Transaction: Update Process, Machine, User"]
    K --> L["IssueDetectionService — scan for anomalies"]
    L --> M[Insert into machines_issues & telemetry_incidents if anomaly found]
    M --> N[Broadcast IncidentCreated via Laravel Reverb if new incident]
    N --> O[Return 200 OK]

• Auth: AltaAuthMiddleware validates PHP Basic Auth, HTTP Basic Auth, or the proprietary Digest scheme.
• Telemetry Sanitization: TelemetryCleaningService whitelists approved keys only, reducing each JSON entry by 96% (from ~14 KB to ~535 bytes average).
• Issue Detection: IssueDetectionService scans the payload for anomalies (HIGH_LATENCY, EXCESSIVE_XRUNS, AUDIO_CRASHED, etc.) and raises or resolves records in machines_issues.
• Real-time Broadcasting: When a new TelemetryIncident is created, the IncidentCreated event is broadcast on the incidents channel via Laravel Reverb (WebSockets), enabling live alerts in the admin dashboard.