# s-inbarasan/traceone architecture

> Architecture diagram of the GitHub repository s-inbarasan/traceone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s-inbarasan/traceone
- Repository: https://github.com/s-inbarasan/traceone

## Overview

#### 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`.

Main entry points: [`lib/context/WorkspaceContext.tsx`](https://github.com/s-inbarasan/traceone/blob/main/lib/context/WorkspaceContext.tsx) (Workspace state), [`app/(dashboard)/layout.tsx`](https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/layout.tsx) (Workspace shell), [`lib/supabase/server.ts`](https://github.com/s-inbarasan/traceone/blob/main/lib/supabase/server.ts) (Supabase), [`app/api/ai/route.ts`](https://github.com/s-inbarasan/traceone/blob/main/app/api/ai/route.ts) (AI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web UI"]
  node_root["Root shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_marketing["Marketing pages<br/>public routes<br/>[layout.tsx]"]
  node_auth["Login and OAuth callback<br/>auth routes<br/>[page.tsx]"]
  node_proxy{{"Request protection<br/>route boundary<br/>[proxy.ts]"}}
  node_dashboard["Workspace shell<br/>authenticated layout<br/>[layout.tsx]"]
  node_workspace["Workspace state<br/>React context"]
  node_project_page["Project workspace<br/>dashboard page<br/>[page.tsx]"]
  node_key_settings["API key settings<br/>dashboard page<br/>[page.tsx]"]
end

subgraph group_server["Server APIs"]
  node_github_api["GitHub endpoints<br/>route handlers<br/>[route.ts]"]
  node_github_service["GitHub service<br/>integration service<br/>[github.ts]"]
  node_project_api["Project APIs<br/>route handlers<br/>[route.ts]"]
  node_domain_services["Project and incident services<br/>domain services<br/>[projects.ts]"]
  node_patch_api["Patch API<br/>route handler<br/>[route.ts]"]
  node_ai_api["AI API<br/>route handler<br/>[route.ts]"]
  node_ai_adapters["AI provider adapters<br/>provider routing<br/>[ai-adapters.ts]"]
  node_keys_api["Key management API<br/>route handler<br/>[route.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_supabase[("Supabase<br/>auth and database<br/>[server.ts]")]
  node_schema["Initial schema<br/>SQL migration"]
  node_github{{"GitHub<br/>source-control platform"}}
  node_ai_providers{{"AI providers<br/>model platforms"}}
end

node_root -->|"renders public routes"| node_marketing
node_root -->|"renders auth routes"| node_auth
node_proxy -->|"permits authenticated access"| node_dashboard
node_dashboard -->|"provides shared state"| node_workspace
node_dashboard -->|"hosts"| node_project_page
node_dashboard -->|"hosts"| node_key_settings
node_workspace -->|"calls"| node_github_api
node_workspace -->|"calls"| node_project_api
node_workspace -->|"calls"| node_patch_api
node_workspace -->|"calls"| node_ai_api
node_key_settings -->|"manages keys"| node_keys_api
node_github_api -->|"delegates"| node_github_service
node_github_service -->|"OAuth and repository data"| node_github
node_project_api -->|"delegates"| node_domain_services
node_domain_services -->|"persists domain data"| node_supabase
node_patch_api -->|"stores patches"| node_supabase
node_keys_api -->|"stores encrypted configuration"| node_supabase
node_ai_api -.->|"resolves credentials"| node_keys_api
node_ai_api -->|"dispatches request"| node_ai_adapters
node_ai_adapters -->|"invokes models"| node_ai_providers
node_supabase -.->|"initialized by"| node_schema

click node_root "https://github.com/s-inbarasan/traceone/blob/main/app/layout.tsx"
click node_marketing "https://github.com/s-inbarasan/traceone/blob/main/app/(marketing)/layout.tsx"
click node_auth "https://github.com/s-inbarasan/traceone/blob/main/app/(auth)/login/page.tsx"
click node_proxy "https://github.com/s-inbarasan/traceone/blob/main/proxy.ts"
click node_dashboard "https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/layout.tsx"
click node_workspace "https://github.com/s-inbarasan/traceone/blob/main/lib/context/WorkspaceContext.tsx"
click node_project_page "https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/projects/%5Bid%5D/page.tsx"
click node_key_settings "https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/settings/keys/page.tsx"
click node_github_api "https://github.com/s-inbarasan/traceone/blob/main/app/api/github/sync/route.ts"
click node_github_service "https://github.com/s-inbarasan/traceone/blob/main/lib/services/github.ts"
click node_project_api "https://github.com/s-inbarasan/traceone/blob/main/app/api/projects/route.ts"
click node_domain_services "https://github.com/s-inbarasan/traceone/blob/main/lib/services/projects.ts"
click node_patch_api "https://github.com/s-inbarasan/traceone/blob/main/app/api/patches/route.ts"
click node_ai_api "https://github.com/s-inbarasan/traceone/blob/main/app/api/ai/route.ts"
click node_ai_adapters "https://github.com/s-inbarasan/traceone/blob/main/lib/services/ai-adapters.ts"
click node_keys_api "https://github.com/s-inbarasan/traceone/blob/main/app/api/keys/route.ts"
click node_supabase "https://github.com/s-inbarasan/traceone/blob/main/lib/supabase/server.ts"
click node_schema "https://github.com/s-inbarasan/traceone/blob/main/supabase/migrations/20240101000000_initial_schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_marketing,node_auth,node_proxy,node_dashboard,node_workspace,node_project_page,node_key_settings toneBlue
class node_github_api,node_github_service,node_project_api,node_domain_services,node_patch_api,node_ai_api,node_ai_adapters,node_keys_api toneAmber
class node_supabase,node_schema,node_github,node_ai_providers toneMint
```

## Components

### Web UI

Next.js App Router route domains and workspace shell.

- [Root shell](https://github.com/s-inbarasan/traceone/blob/main/app/layout.tsx): Next.js layout · `app/layout.tsx`
- [Marketing pages](https://github.com/s-inbarasan/traceone/blob/main/app/(marketing)/layout.tsx): public routes · `app/(marketing)/layout.tsx`
- [Login and OAuth callback](https://github.com/s-inbarasan/traceone/blob/main/app/(auth)/login/page.tsx): auth routes · `app/(auth)/login/page.tsx`
- [Request protection](https://github.com/s-inbarasan/traceone/blob/main/proxy.ts): route boundary · Protects or forwards session-aware requests. · `proxy.ts`
- [Workspace shell](https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/layout.tsx): authenticated layout · `app/(dashboard)/layout.tsx`
- [Workspace state](https://github.com/s-inbarasan/traceone/blob/main/lib/context/WorkspaceContext.tsx): React context · Shared client state used by dashboard workflows. · `lib/context/WorkspaceContext.tsx`
- [Project workspace](https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/projects/%5Bid%5D/page.tsx): dashboard page · `app/(dashboard)/projects/[id]/page.tsx`
- [API key settings](https://github.com/s-inbarasan/traceone/blob/main/app/(dashboard)/settings/keys/page.tsx): dashboard page · `app/(dashboard)/settings/keys/page.tsx`

### Server APIs

Route handlers and domain service boundaries.

- [GitHub endpoints](https://github.com/s-inbarasan/traceone/blob/main/app/api/github/sync/route.ts): route handlers · Connects, syncs, reads files, and inspects pull requests. · `app/api/github/sync/route.ts`
- [GitHub service](https://github.com/s-inbarasan/traceone/blob/main/lib/services/github.ts): integration service · `lib/services/github.ts`
- [Project APIs](https://github.com/s-inbarasan/traceone/blob/main/app/api/projects/route.ts): route handlers · `app/api/projects/route.ts`
- [Project and incident services](https://github.com/s-inbarasan/traceone/blob/main/lib/services/projects.ts): domain services · `lib/services/projects.ts`
- [Patch API](https://github.com/s-inbarasan/traceone/blob/main/app/api/patches/route.ts): route handler · Stores generated remediation artifacts. · `app/api/patches/route.ts`
- [AI API](https://github.com/s-inbarasan/traceone/blob/main/app/api/ai/route.ts): route handler · Resolves workspace credentials and selected provider server-side. · `app/api/ai/route.ts`
- [AI provider adapters](https://github.com/s-inbarasan/traceone/blob/main/lib/services/ai-adapters.ts): provider routing · `lib/services/ai-adapters.ts`
- [Key management API](https://github.com/s-inbarasan/traceone/blob/main/app/api/keys/route.ts): route handler · `app/api/keys/route.ts`

### Infrastructure

Persistence, identity, and external providers.

- [Supabase](https://github.com/s-inbarasan/traceone/blob/main/lib/supabase/server.ts): auth and database · Backs authentication and application persistence. · `lib/supabase/server.ts`
- [Initial schema](https://github.com/s-inbarasan/traceone/blob/main/supabase/migrations/20240101000000_initial_schema.sql): SQL migration · `supabase/migrations/20240101000000_initial_schema.sql`
- **GitHub**: source-control platform
- **AI providers**: model platforms

## Connections

- Root shell → Marketing pages: renders public routes
- Root shell → Login and OAuth callback: renders auth routes
- Request protection → Workspace shell: permits authenticated access
- Workspace shell → Workspace state: provides shared state
- Workspace shell → Project workspace: hosts
- Workspace shell → API key settings: hosts
- Workspace state → GitHub endpoints: calls
- Workspace state → Project APIs: calls
- Workspace state → Patch API: calls
- Workspace state → AI API: calls
- API key settings → Key management API: manages keys
- GitHub endpoints → GitHub service: delegates
- GitHub service → GitHub: OAuth and repository data
- Project APIs → Project and incident services: delegates
- Project and incident services → Supabase: persists domain data
- Patch API → Supabase: stores patches
- Key management API → Supabase: stores encrypted configuration
- AI API → Key management API: resolves credentials
- AI API → AI provider adapters: dispatches request
- AI provider adapters → AI providers: invokes models
- Supabase → Initial schema: initialized by