How darknightdesigner/not-a-wrapper works
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: route.ts Chat API · page.tsx Chat routes · schema.ts Convex domain · provider.tsx Client stores
Components 19
Next.js app
Routes, UI shells, and browser-facing interactions
- App shell · Global layout, providers, middleware, and top-level pages
app/layout.tsx - Chat routes · Primary chat, project, share, auth, and setup pages
app/c/[chatId]/page.tsx - Chat API · Main request pipeline for provider adapters, replay, intent, and tool handling
app/api/chat/route.ts - Support APIs · Models, projects, preferences, keys, guests, rate limits, health, CSRF, webhooks, and MCP status
app/api/models/route.ts - Chat UI · Message rendering, input, uploads, tool UI, sources, and client state hooks
app/components/chat/chat.tsx - Multi-chat · Runs one prompt across multiple models and renders side-by-side comparisons
app/components/multi-chat/multi-chat.tsx - History & nav · Sidebar, history search, project navigation, and layout actions
app/components/layout/sidebar/app-sidebar.tsx - Settings · Appearance, models, keys, MCP connections, tools, and account settings
app/components/layout/settings/settings-content.tsx - Provider 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 · Normalized model definitions and provider metadata exposed to the UI and API
lib/models/index.ts - Tool policy · Capability checks, naming, truncation, platform rules, and UI metadata for tools
lib/tools/policy.ts - MCP runtime · Loads local or remote MCP servers, validates them, and applies truncation and circuit breaking
lib/mcp/load-tools.ts - Auth & keys · Clerk auth, guest access, webhook sync, and encrypted BYOK storage
lib/encryption.ts - Client stores · Abstracted chat, model, user, and preference stores that keep the UI synced with backend state
lib/chat-store/chats/provider.tsx - Telemetry · PostHog analytics plus Sentry tracing, scrubbing, and chat error taxonomy
lib/observability/sentry-tracing.ts - AI orchestration · 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 · Chats, messages, projects, files, preferences, usage, feedback, approvals, and tool logs
convex/schema.ts - Tool logs · Persisted tool-call, MCP tool-call, approval, and tool-state records
convex/toolCallLog.ts - Files & uploads · Convex-backed file attachments and upload state used by chat and tools
convex/files.ts
Connections 25
- 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