TrialController

Kind: Controller

Source: atloria-monorepo/apps/api/src/trial/trial.controller.ts

Anonymous one-click trial for PUBLIC GitHub repos (Phase 1.1). Rate-limited per IP by the AI cost guard + a global daily cap inside the service.

TrialController exposes the anonymous one-click trial flow for public GitHub repositories. It accepts trial requests, delegates repository analysis and trial creation to the underlying service layer, and relies on AI cost guards and daily limits to prevent abuse.

Diagram

mermaid
graph LR
  Client[Anonymous User / Client] -->|Trial request with public GitHub repo| Controller[TrialController]
  Controller --> Guard[AI Cost Guard / IP Rate Limit]
  Guard --> Service[Trial Service]
  Service --> GitHub[Public GitHub Repository]
  Service --> AI[AI Analysis Pipeline]
  Service --> Cap[Global Daily Trial Cap]
  Service --> Result[Trial Result]
  Result --> Client

Usage

ts
// Example client-side request to start an anonymous trial.
// The repository must be publicly accessible on GitHub.

const response = await fetch("/trial", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    repositoryUrl: "https://github.com/example/public-repository",
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.message ?? "Unable to start trial");
}

const trial = await response.json();

console.log("Trial created:", trial);

AI Coding Instructions

• Keep TrialController thin: validate request input and delegate trial orchestration to the trial service.
• Preserve anonymous access behavior; do not add authentication requirements unless the trial product flow changes.
• Ensure trial requests only target public GitHub repositories and return clear validation errors for inaccessible or invalid URLs.
• Do not bypass the AI cost guard, per-IP rate limiting, or global daily trial cap when adding new trial endpoints.
• Avoid placing GitHub API calls or AI-processing logic directly in the controller; keep those integrations in dedicated services.

Relationships

• MODULE_DECLARES → generate
• MODULE_DECLARES → status
• MODULE_DECLARES → claim
• DEPENDS_ON → TrialService

Referenced By

• TrialModule (MODULE_DECLARES)