# darknightdesigner/not-a-wrapper architecture

> Architecture diagram of the GitHub repository darknightdesigner/not-a-wrapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darknightdesigner/not-a-wrapper
- Repository: https://github.com/darknightdesigner/not-a-wrapper

## Overview

1. **Overall shape**
   - This is a Next.js 16 App Router application with a thin server/UI boundary and a separate Convex backend for reactive data, auth-aware persistence, and file storage.
   - The main runtime is browser UI + Next.js server routes; the main external dependencies are Convex, Clerk, multiple AI providers, PostHog, and MCP tool servers.

2. **Primary user-facing surfaces**
   - `app/` contains the routes and page shells: chat pages (`/c/[chatId]`), project pages (`/p/[projectId]`), public share pages (`/share/[chatId]`), and auth pages.
   - `app/components/` holds the feature-level UI composition: chat, multi-chat comparison, sidebar/layout, history/search, settings, and tool/file upload interactions.
   - `components/` is the shared design-system layer, mostly reusable primitives and provider/model-specific UI.

3. **Chat request pipeline**
   - The core interaction is routed through `app/api/chat/route.ts` and the files under `app/api/chat/`.
   - That pipeline is split into provider adapters, intent detection, replay/normalization logic, search-tool handling, and shared utilities, which suggests the chat endpoint is responsible for turning one UI prompt into provider-specific streaming responses and tool calls.
   - The streaming response path is the main server-side orchestration boundary in the app.

4. **AI provider abstraction**
   - `lib/models/` defines the model catalog; `lib/openproviders/` maps providers to runtime capabilities and environment access; `app/api/models/route.ts` exposes model metadata to the UI.
   - Provider-specific chat handling is isolated in `app/api/chat/adapters/`, with separate implementations for OpenAI, Anthropic, Google, OpenAI-compatible providers, and text-only fallbacks.
   - This boundary is important because the UI deals in normalized model choices, while the backend adapts to different message formats, tool semantics, and reasoning/streaming behaviors.

5. **Tools, web search, and MCP**
   - `lib/tools/` is the policy layer for tool availability, capability checks, naming, truncation, platform rules, and UI metadata.
   - `lib/mcp/` handles loading MCP servers from local or URL sources, validation, truncation, and circuit breaking; the corresponding routes in `app/api/mcp-servers/` manage status and test operations.
   - Tool execution is auditable: `convex/toolCallLog.ts`, `convex/mcpToolCallLog.ts`, and approvals-related tables indicate that tool use is persisted and gated rather than executed ad hoc.

6. **Data and persistence boundary**
   - Convex is the primary backend datastore and reactive sync layer. The schema and functions in `convex/` cover chats, messages, projects, files, user keys, preferences, usage, feedback, MCP servers, approvals, and tool logs.
   - Client-side access is abstracted through providers under `lib/chat-store/`, `lib/model-store/`, `lib/user-store/`, and `lib/user-preference-store/`, which makes the UI reactive without directly talking to the database.
   - File uploads are Convex-backed, so attachments are part of the same persistence story as chat history rather than an external blob service.

7. **Authentication and access control**
   - Clerk is the auth layer, with routes under `app/auth/` and a webhook at `app/api/webhooks/clerk/route.ts`.
   - There is also guest access, supported by `app/api/create-guest/` and rate-limit endpoints, which means the app has two access modes: authenticated users with persistent settings and anonymous users with constrained usage.
   - `middleware.ts` likely enforces the route-level auth/session boundary.

8. **BYOK and sensitive data handling**
   - The app supports Bring Your Own Key, and `lib/encryption.ts` plus user-key routes indicate API keys are encrypted at rest before being stored.
   - User key status, creation, and management are separated into dedicated API routes, which keeps credential handling out of the general chat pipeline.
   - This is a major architectural boundary because provider access can come from the app operator or directly from the user’s own stored secrets.

9. **Conversation organization and sharing**
   - Chats are organized into projects, with dedicated project routes and Convex project models.
   - Public sharing is a separate surface under `app/share/[chatId]`, implying shared chats are rendered from persisted conversation state rather than live session state.
   - History/search UI in `app/components/history/` and sidebar/project management in `app/components/layout/sidebar/` show that conversation navigation is a first-class subsystem, not just a sidebar detail.

10. **Multi-chat comparison mode**
   - `app/components/multi-chat/` and the related UI allow one prompt to be run across multiple models simultaneously.
   - This is architecturally distinct from single-chat because it multiplexes one user input into multiple provider/model streams and then renders them side-by-side.
   - The comparison layer depends heavily on the same model registry, but has its own orchestration and view-state hooks.

11. **Message rendering and client interaction state**
   - `app/components/chat/` contains the conversation renderer, assistant/user message components, tool invocation UI, sources, feedback, and file-upload integration.
   - Local UI behavior is managed by hooks like `use-chat-core`, `use-chat-operations`, `use-loading-state`, `use-reasoning-phase`, and `use-file-upload`.
   - This layer is the browser-side boundary between raw streamed assistant events and the finished conversational UI.

12. **Analytics and observability**
   - PostHog is wired through `app/providers/posthog-provider.tsx` and related client components for page views and product analytics.
   - Sentry instrumentation/config files and `lib/observability/` show error tracing/scrubbing and chat-specific error taxonomy, so operational telemetry is built into the app rather than bolted on.
   - The observability layer matters because AI chat involves long-lived streaming requests, provider failures, and tool-call errors.

13. **API surface beyond chat**
   - There are dedicated routes for health, CSRF, providers, rate limits, user preferences, favorite models, projects, chat creation, model listing, and Payclaw status.
   - This suggests the app exposes a fairly broad internal API used by the client shell, not just a single chat endpoint.
   - The API layer is therefore the main boundary for session creation, settings management, and operational checks.

14. **Repo organization and implementation style**
   - `app/` is the feature shell, `lib/` contains shared business logic, `convex/` is the persisted backend, and `components/` holds reusable UI primitives and model/provider icons.
   - The `.agents/` content is extensive internal design/research documentation and does not appear to be runtime code; it supports implementation decisions but does not affect the deployed architecture.
   - For a diagram, the important flows are: browser UI → Next.js routes/components → chat orchestration API → provider/MCP/tool services, with Convex providing the persistent state and Clerk/PostHog providing identity and telemetry.

Main entry points: [`app/api/chat/route.ts`](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/chat/route.ts) (Chat API), [`app/c/[chatId]/page.tsx`](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/c/[chatId]/page.tsx) (Chat routes), [`convex/schema.ts`](https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/schema.ts) (Convex domain), [`lib/chat-store/chats/provider.tsx`](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/chat-store/chats/provider.tsx) (Client stores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_app_shell["App shell<br/>Next.js App Router<br/>[layout.tsx]"]
  node_chat_routes["Chat routes<br/>UI routes<br/>[page.tsx]"]
  node_api_chat{{"Chat API<br/>streaming endpoint<br/>[route.ts]"}}
  node_api_aux{{"Support APIs<br/>route set<br/>[route.ts]"}}
  node_chat_ui["Chat UI<br/>conversation shell<br/>[chat.tsx]"]
  node_multi_chat["Multi-chat<br/>comparison UI<br/>[multi-chat.tsx]"]
  node_history_sidebar["History & nav<br/>navigation UI<br/>[app-sidebar.tsx]"]
  node_settings_ui["Settings<br/>preferences UI"]
  node_provider_adapters{{"Provider adapters<br/>runtime adapters<br/>[index.ts]"}}
end

subgraph group_lib["Shared logic"]
  node_provider_registry["Model registry<br/>catalog<br/>[index.ts]"]
  node_tool_policy["Tool policy<br/>tooling layer<br/>[policy.ts]"]
  node_mcp_runtime["MCP runtime<br/>MCP orchestration<br/>[load-tools.ts]"]
  node_auth_keys["Auth & keys<br/>security boundary<br/>[encryption.ts]"]
  node_stores["Client stores<br/>reactive data layer<br/>[provider.tsx]"]
  node_observability["Telemetry<br/>observability<br/>[sentry-tracing.ts]"]
  node_ai_orchestration["AI orchestration<br/>shared AI logic<br/>[index.ts]"]
end

subgraph group_convex["Convex backend"]
  node_convex_chats[("Convex domain<br/>data model<br/>[schema.ts]")]
  node_convex_tools[("Tool logs<br/>audit trail<br/>[toolCallLog.ts]")]
  node_convex_files[("Files & uploads<br/>storage model<br/>[files.ts]")]
end

node_app_shell -->|"renders"| node_chat_routes
node_app_shell -->|"hosts"| node_chat_ui
node_chat_routes -->|"uses"| node_chat_ui
node_chat_routes -->|"uses"| node_history_sidebar
node_chat_routes -->|"opens"| node_settings_ui
node_chat_ui -->|"streams"| node_api_chat
node_multi_chat -->|"reads"| node_provider_registry
node_multi_chat -->|"fans out"| node_api_chat
node_api_chat -->|"delegates"| node_provider_adapters
node_api_chat -->|"normalizes"| node_ai_orchestration
node_api_chat -->|"checks"| node_tool_policy
node_api_chat -->|"loads"| node_mcp_runtime
node_api_chat -->|"persists"| node_convex_chats
node_api_chat -->|"audits"| node_convex_tools
node_api_chat -->|"stores"| node_convex_files
node_api_aux -->|"serves"| node_provider_registry
node_api_aux -->|"manages"| node_auth_keys
node_settings_ui -->|"edits"| node_auth_keys
node_settings_ui -->|"reads"| node_convex_chats
node_stores -->|"syncs"| node_convex_chats
node_stores -->|"syncs"| node_convex_files
node_stores -->|"hydrates"| node_provider_registry
node_convex_chats -->|"references"| node_convex_tools
node_observability -->|"instruments"| node_api_chat
node_observability -->|"collects"| node_app_shell

click node_app_shell "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/layout.tsx"
click node_chat_routes "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/c/[chatId]/page.tsx"
click node_api_chat "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/chat/route.ts"
click node_api_aux "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/models/route.ts"
click node_chat_ui "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/chat/chat.tsx"
click node_multi_chat "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/multi-chat/multi-chat.tsx"
click node_history_sidebar "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/layout/sidebar/app-sidebar.tsx"
click node_settings_ui "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/layout/settings/settings-content.tsx"
click node_provider_registry "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/models/index.ts"
click node_provider_adapters "https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/chat/adapters/index.ts"
click node_tool_policy "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/tools/policy.ts"
click node_mcp_runtime "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/mcp/load-tools.ts"
click node_auth_keys "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/encryption.ts"
click node_stores "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/chat-store/chats/provider.tsx"
click node_convex_chats "https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/schema.ts"
click node_convex_tools "https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/toolCallLog.ts"
click node_convex_files "https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/files.ts"
click node_observability "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/observability/sentry-tracing.ts"
click node_ai_orchestration "https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/ai/index.ts"

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_app_shell,node_chat_routes,node_api_chat,node_api_aux,node_chat_ui,node_multi_chat,node_history_sidebar,node_settings_ui,node_provider_adapters toneBlue
class node_provider_registry,node_tool_policy,node_mcp_runtime,node_auth_keys,node_stores,node_observability,node_ai_orchestration toneAmber
class node_convex_chats,node_convex_tools,node_convex_files toneMint
```

## Components

### Next.js app

Routes, UI shells, and browser-facing interactions

- [App shell](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/layout.tsx): Next.js App Router · Global layout, providers, middleware, and top-level pages · `app/layout.tsx`
- [Chat routes](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/c/[chatId]/page.tsx): UI routes · Primary chat, project, share, auth, and setup pages · `app/c/[chatId]/page.tsx`
- [Chat API](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/chat/route.ts): streaming endpoint · Main request pipeline for provider adapters, replay, intent, and tool handling · `app/api/chat/route.ts`
- [Support APIs](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/models/route.ts): route set · Models, projects, preferences, keys, guests, rate limits, health, CSRF, webhooks, and MCP status · `app/api/models/route.ts`
- [Chat UI](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/chat/chat.tsx): conversation shell · Message rendering, input, uploads, tool UI, sources, and client state hooks · `app/components/chat/chat.tsx`
- [Multi-chat](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/multi-chat/multi-chat.tsx): comparison UI · Runs one prompt across multiple models and renders side-by-side comparisons · `app/components/multi-chat/multi-chat.tsx`
- [History & nav](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/layout/sidebar/app-sidebar.tsx): navigation UI · Sidebar, history search, project navigation, and layout actions · `app/components/layout/sidebar/app-sidebar.tsx`
- [Settings](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/components/layout/settings/settings-content.tsx): preferences UI · Appearance, models, keys, MCP connections, tools, and account settings · `app/components/layout/settings/settings-content.tsx`
- [Provider adapters](https://github.com/darknightdesigner/not-a-wrapper/blob/main/app/api/chat/adapters/index.ts): runtime adapters · Provider-specific chat formatting and streaming behavior for OpenAI, Anthropic, Google, compatible, and fallback modes · `app/api/chat/adapters/index.ts`

### Shared logic

Modeling, orchestration, tools, stores, and integrations

- [Model registry](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/models/index.ts): catalog · Normalized model definitions and provider metadata exposed to the UI and API · `lib/models/index.ts`
- [Tool policy](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/tools/policy.ts): tooling layer · Capability checks, naming, truncation, platform rules, and UI metadata for tools · `lib/tools/policy.ts`
- [MCP runtime](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/mcp/load-tools.ts): MCP orchestration · Loads local or remote MCP servers, validates them, and applies truncation and circuit breaking · `lib/mcp/load-tools.ts`
- [Auth & keys](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/encryption.ts): security boundary · Clerk auth, guest access, webhook sync, and encrypted BYOK storage · `lib/encryption.ts`
- [Client stores](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/chat-store/chats/provider.tsx): reactive data layer · Abstracted chat, model, user, and preference stores that keep the UI synced with backend state · `lib/chat-store/chats/provider.tsx`
- [Telemetry](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/observability/sentry-tracing.ts): observability · PostHog analytics plus Sentry tracing, scrubbing, and chat error taxonomy · `lib/observability/sentry-tracing.ts`
- [AI orchestration](https://github.com/darknightdesigner/not-a-wrapper/blob/main/lib/ai/index.ts): shared AI logic · Message conversion, context management, and sub-agent coordination utilities · `lib/ai/index.ts`

### Convex backend

Reactive persistence, auth-aware data, and file/tool state

- [Convex domain](https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/schema.ts): data model · Chats, messages, projects, files, preferences, usage, feedback, approvals, and tool logs · `convex/schema.ts`
- [Tool logs](https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/toolCallLog.ts): audit trail · Persisted tool-call, MCP tool-call, approval, and tool-state records · `convex/toolCallLog.ts`
- [Files & uploads](https://github.com/darknightdesigner/not-a-wrapper/blob/main/convex/files.ts): storage model · Convex-backed file attachments and upload state used by chat and tools · `convex/files.ts`

## Connections

- App shell → Chat routes: renders · Provides the application shell for route-based pages
- App shell → Chat UI: hosts · Provides providers and client layout for the chat experience
- Chat routes → Chat UI: uses · Pages compose the main chat conversation and input surfaces
- Chat routes → History & nav: uses · Routes share the sidebar and history navigation shell
- Chat routes → Settings: opens · Settings are surfaced from the main app routes and layout
- Chat UI → Chat API: streams · Sends prompts and receives streamed assistant responses
- Multi-chat → Model registry: reads · Uses the normalized model catalog for comparison runs
- Multi-chat → Chat API: fans out · Multiplexes a prompt across multiple model/provider executions
- Chat API → Provider adapters: delegates · Selects provider-specific request/response handling
- Chat API → AI orchestration: normalizes · Converts messages, context, and sub-agent state for execution
- Chat API → Tool policy: checks · Applies tool availability and routing policy before execution
- Chat API → MCP runtime: loads · Resolves external MCP tools and server definitions
- Chat API → Convex domain: persists · Writes chat and message state through the backend boundary
- Chat API → Tool logs: audits · Records tool calls and approvals for replayable execution
- Chat API → Files & uploads: stores · Attaches uploaded files and related chat artifacts
- Support APIs → Model registry: serves · Exposes model metadata and provider capability info to the UI
- Support APIs → Auth & keys: manages · Handles auth/session-sensitive operations for guests, keys, and webhooks
- Settings → Auth & keys: edits · User-facing key management and status flows connect to encrypted storage
- Settings → Convex domain: reads · Preferences and settings are backed by reactive Convex state
- Client stores → Convex domain: syncs · Client stores subscribe to the reactive backend for chat data
- Client stores → Files & uploads: syncs · Uploads and attachment state are reflected in the UI layer
- Client stores → Model registry: hydrates · Model selections and visibility settings use the catalog data
- Convex domain → Tool logs: references · Conversation data links to tool execution logs and approvals
- Telemetry → Chat API: instruments · Tracks streaming failures, provider issues, and chat error taxonomy
- Telemetry → App shell: collects · Page views and app-level telemetry are wired through the client shell
