Documentation

Aura is an event-driven AI orchestration workspace that eliminates the friction of open-source onboarding. It transforms chaotic GitHub threads into structured, actionable tasks and provisions contributor environments with a single click. Built with Next.js 14 (App Router), React Server Components, and the Lemma SDK, Aura represents a new paradigm in developer tooling — one where AI operates as invisible background workers rather than chatbots.

Aura follows a three-phase pipeline architecture: 1. Ingestion — GitHub webhooks are received and verified via HMAC-SHA256. Issue payloads are parsed and stored in the Lemma database with a "triage" status. 2. Translation — A background Lemma agent ("The Translator") intercepts raw maintainer comments and distills them into plain-English action items using context-aware NLP. 3. Execution — The contributor clicks "Sync to IDE" which triggers a Next.js Server Action. This dispatches a command to the local Lemma daemon which clones the repo, installs dependencies, and opens VS Code with full context.

POST /api/webhooks/github Receives GitHub webhook payloads. Validates x-hub-signature-256 using crypto.timingSafeEqual() to prevent timing attacks. Extracts issue_id, repo_name, and raw comments, then inserts into the assigned_issues table. GET /api/logs/stream Returns a Server-Sent Events (SSE) stream using ReadableStream. Emits real-time daemon execution logs with keep-alive pings. Uses the cancel() handler to properly clean up intervals on client disconnect.

syncTask(issueId, targetFiles) A secure server-side function marked with "use server". It dispatches a POST request to the Lemma daemon at /api/daemon/dispatch, updates the issue status from "triage" to "coding", and calls revalidatePath('/') to flush the Next.js cache and re-render the dashboard without a full page reload.

Server Components: • page.tsx — Async RSC that fetches data directly from the Lemma SDK on the server. Zero client-side loading spinners. • StatsBar — Renders real-time metrics about the triage queue. Client Components: • SyncButton — Manages a four-state machine (idle → syncing → done → error) with visual feedback for each state. • TerminalFeed — Connects to the SSE endpoint via the native EventSource API. Parses log types, applies semantic coloring, and auto-scrolls with useRef.

• Webhook Verification: All GitHub payloads are verified using HMAC-SHA256 with timing-safe comparison. • Server Actions: All mutations are executed server-side via the "use server" directive, never exposed to the client. • Environment Secrets: GITHUB_WEBHOOK_SECRET is loaded from process.env and never bundled into client code. • Input Validation: Issue IDs and repository names are validated before database insertion.

The Lemma SDK provides a chained, async API for database operations: lemma.table('assigned_issues').select('*').eq('status', 'triage') lemma.table('assigned_issues').insert({ issue_id, repo_name, status: 'triage' }) lemma.table('assigned_issues').update({ status: 'coding' }).eq('issue_id', id) For local development, a mock SDK at src/lib/lemma-sdk.ts simulates these operations with static data, allowing full UI/UX development without a running Lemma instance.

Prerequisites: • Node.js 18+ • Docker or Podman (for Lemma runtime) 1. Start the Lemma platform: curl -fsSL https://raw.githubusercontent.com/lemma-work/lemma-platform/main/install.sh | bash 2. Initialize the Aura pod: cd lemma-pod && lemma pod import ./aura-workspace 3. Run the dashboard: npm install && npm run dev 4. Open http://localhost:3000