Phase 6: AI Quota & Telemetry Subsystems

This document dissects the economics and observability of the AI inference engine. The system relies on a strict quota-based throttle governed by the active subscription tier and a dedicated telemetry layer that audits every generation for live dashboards.

1. The Quota Context: Service Resolution

The AiUsageService is responsible for gatekeeping access to Groq/Llama 70b based on subscription entitlements.

Resolution Chain: The service queries PlanService::resolveQuotaPlan($user) to find the monthly quota. It handles three states elegantly:

The user has no subscriptions: It falls back to the Free tier quota.

The user has expired subscriptions: It throws a descriptive Exception.

The user has an active subscription: It uses that plan's ai_quota_monthly.

Monthly Reset: Before consumption, it evaluates user->ai_reset_at. If the timestamp is in the past, it automatically resets the generation counter and extends the window by one month.

2. The Atomic Consumption Guard

To prevent race conditions when a user spams the generation endpoint, the quota write is not a naive PHP ++. It uses a raw UPDATE WHERE query that only succeeds if the condition holds:

Atomicity: If two requests hit simultaneously and only one quota remains, only the first UPDATE will affect 1 row. The second will affect 0 rows.

Handling: If zero rows were updated, the service throws "You have exhausted your monthly AI quota."

3. MD5 Caching & Fallback Architecture

The most economically vital code is in GroqService.php. It implements Markdown-stripped caching to prevent repeated LLM inference from consuming quota or incurring cost.

As seen in GroqService::review, the generation is strictly wrapped in Cache::remember():

The Lifecycle

Hit: The controller generates a deterministic md5 hash of the requested prompt/trip data and asks the Cache.

Consume: On a Cache Miss, the quota is consumed atomically inside the remember closure. If quota is exhausted, the request fails.

Inference: Groq (Llama 3.3 70b) is called.

Success: The response is cached for 60 minutes.

Cache Hit: On the next identical request, the closure is never executed. The result is served instantly by Redis, and no quota is consumed.

The Graceful Fallback

If quota is exhausted, or if the external API throws an exception, the outer AiController::generate catches it cleanly and falls back to a deterministic procedural generator. It perfectly synthesizes an N-day itinerary using templates and calculated offsets, ensuring the endpoint is always available.

4. Telemetry Auditing (`AiGeneration`)

Regardless of whether the response came from Cache, LLM, or the Fallback, the AiController::logGeneration method writes a strict telemetry event to the AiGeneration database table.

This data never throws exceptions (try/catch swallowed with a Log::warning), ensuring the user's actual itinerary is saved even if the telemetry database is temporarily unavailable. This dataset directly powers the Live Command Center monitoring shell.

Phase 6: AI Quota &amp; Telemetry Subsystems

1. The Quota Context: Service Resolution#

2. The Atomic Consumption Guard#

3. MD5 Caching & Fallback Architecture#

The Lifecycle#

The Graceful Fallback#

4. Telemetry Auditing (AiGeneration)#

5. Data Flow: Quota & Caching#