s-inbarasan/traceone

Purpose and Runtime

This is a Next.js App Router application for a developer operations workspace: users connect GitHub repositories, manage projects, inspect pull requests/incidents, generate AI-assisted output, and configure provider API keys. It runs as a React/TypeScript web application with server route handlers and Supabase-backed persistence.

Primary entry points are the root shell at app/layout.tsx, route-group layouts/pages under app/(marketing), app/(auth), and app/(dashboard), plus HTTP endpoints under app/api.

Route and Access Segmentation

The UI is intentionally split into three route domains:

• Public marketing/legal pages: app/(marketing)/page.tsx, app/(marketing)/layout.tsx, app/(marketing)/privacy/page.tsx.

• Authentication flow: app/(auth)/login/page.tsx and OAuth return handling in app/auth/callback/route.ts.

• Authenticated workspace/dashboard: app/(dashboard)/layout.tsx, app/(dashboard)/dashboard/page.tsx, and feature pages such as app/(dashboard)/projects/[id]/page.tsx.

proxy.ts is the likely request-boundary location for route protection or session-aware forwarding.

Workspace State and Dashboard Shell

The dashboard layout provides the persistent application shell and navigation, grounded in app/(dashboard)/layout.tsx, components/layout/sidebar.tsx, and components/layout/header.tsx.

Client-side shared workspace state is centralized in lib/context/WorkspaceContext.tsx. Dashboard pages consume this context and invoke API routes rather than directly coupling page code to external systems. Main user workflows include projects, pull requests, incidents, onboarding, and API-key settings.

GitHub Integration Boundary

GitHub is isolated behind service code and dedicated API handlers. lib/services/github.ts is the core integration abstraction; route handlers expose repository connection, discovery, synchronization, files, and PR inspection:

• app/api/github/connect/route.ts

• app/api/github/sync/route.ts

• app/api/github/pull-request/route.ts

• app/api/github/file-content/route.ts

The expected flow is OAuth/session-backed account connection → repository listing/selection → sync into project data → repository file and pull-request/check retrieval for dashboard and AI workflows.

Project, Incident, and Patch Domain APIs

Application-owned operational data is separated into service modules and REST-like route handlers. Project and incident behavior is represented by lib/services/projects.ts, lib/services/incidents.ts, app/api/projects/route.ts, and app/api/incidents/[id]/route.ts.

Patch generation/storage is independently exposed at app/api/patches/route.ts; diff processing support resides in lib/utils/diff.ts. This establishes a boundary between source-control retrieval, AI analysis, and persisted remediation artifacts.

AI Provider and API-Key Routing

AI requests enter through app/api/ai/route.ts and are dispatched through provider adapters in lib/services/ai-adapters.ts. Key management is a separate server boundary at app/api/keys/route.ts, with user configuration surfaced at app/(dashboard)/settings/keys/page.tsx.

The README specifically identifies end-to-end API key integration and provider routing as complete. This implies AI execution should resolve a user/workspace key and selected provider server-side, avoiding direct provider credentials in browser code.

Persistence and External Infrastructure

Supabase is the persistence and authentication infrastructure, with environment-specific clients at lib/supabase/client.ts and lib/supabase/server.ts. The initial relational schema is defined in supabase/migrations/20240101000000_initial_schema.sql.

Material external dependencies are Supabase for auth/data, GitHub for repository and pull-request data, and one or more AI model providers accessed through the adapter layer. Environment requirements are indicated by .env.example.