> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drdj.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Repo Map

> Platform-oriented map of critical folders and files for fast onboarding.

## Key Folders

* `/client`: frontend application
* `/server`: API routes, middleware, jobs
* `/shared`: shared contracts/helpers
* `/migrations`: schema migrations
* `/tests`: unit/integration/e2e suites
* `/whatsapp-extension-react`: WhatsApp extension
* `/linkshot-extension`: LinkShot extension
* `/plugins`: repo-local Codex plugins, MCP servers, plugin skills, and assets

## High-Value Files

* `/server/index.ts`: middleware and route mount order
* `/server/middleware/auth.ts`: authentication enforcement
* `/server/middleware/agent-auth.ts`: service-secret and acting-user auth for MCP agent calls
* `/server/routes/settings.ts`: account settings and AI Agent Connection status endpoint
* `/server/db/schema.ts`: entity and enum definitions
* `/shared/agentBridge.ts`: provider-neutral agent route schema and allowlist
* `/migrations/add-agent-approvals.sql`: persistent approval records for sensitive agent writes
* `/migrations/extend-shortener-for-ai-agents.sql`: drdj.me shortener ownership, safety, and analytics fields
* `/server/lib/short-links.ts`: shared short-link validation, slug, expiry, rate-limit, and analytics helpers
* `/server/routes/shortener-v1.ts`: standalone `/api/shortener/v1/*` API for AI agents
* `/client/src/pages/Links.tsx`: authenticated short-link dashboard and control plane
* `/client/src/pages/marketing/AiLinkShortener.tsx`: public drdj.me AI shortener landing page
* `/client/src/lib/shortenerPrompt.ts`: short agent prompt builder for copy/paste workflows
* `/client/src/pages/tools/ToolsIndex.tsx`: authenticated Tools hub for website utilities and integrations
* `/client/src/pages/tools/AIAgentSetupTool.tsx`: Tools page wrapper for BYOA MCP setup and diagnostics
* `/client/src/components/settings/AIAgentConnectionSection.tsx`: BYOA MCP settings card, permission tiers, and scoped logs
* `/client/src/contexts/AuthContext.tsx`: frontend auth state lifecycle
* `/client/src/lib/axios.ts`: auth header + 401 handling

## In-App AI Copilot

* `/server/lib/copilot/model.ts`: per-user provider/model resolution (`resolveCopilotModel`)
* `/server/lib/copilot/providerConfig.ts`: userId-scoped `copilot_provider_config` access (RLS)
* `/server/lib/crypto.ts`: AES-256-GCM encryption for per-user BYOK keys and Codex token blob
* `/server/lib/copilot/modelCatalog.ts`: curated OpenRouter model catalog for the settings picker
* `/server/lib/copilot/freeRotation.ts`: `free-rotate` failover across the tool-capable free pool
* `/server/lib/copilot/codex.ts`: experimental Codex/ChatGPT-subscription provider (flag-gated, off by default)
* `/server/lib/copilot/learning.ts`: per-user self-learning (signal → graduate → inject → curate)
* `/server/lib/copilot/agent.ts`: per-request `BuiltInAgent` assembly and prompt injection
* `/server/lib/copilot/api.ts`: loopback HTTP client that calls `/api/*` with the user's JWT
* `/server/lib/copilot/tool.ts`: `defineTool` wrapper with provider-error redaction
* `/server/lib/copilot/config.ts`: provider-agnostic readiness check (`isCopilotConfigured`)
* `/server/lib/copilot/tools/*`: the 42 server tools across 11 families
* `/server/lib/appSettings.ts`: global `app_settings` access (`SystemSettings`, TTL cache + invalidation)
* `/server/routes/copilot.ts`: self-hosted CopilotKit runtime endpoint (`/api/copilot`)
* `/server/routes/copilotConfig.ts`: `GET`/`PUT /api/copilot/provider-config`
* `/server/routes/copilotFeedback.ts`: `POST /api/copilot/feedback` (HITL learning signals)
* `/server/routes/adminCopilot.ts`: admin-only cross-user `/api/admin/copilot/*` dashboard endpoints
* `/server/lib/copilot/admin.ts`: cross-user admin query layer (redacted; separate from per-user functions)
* `/server/middleware/maintenance.ts`: maintenance-mode gate blocking non-admin `/api` traffic (fail-open)
* `/client/src/pages/admin/Copilot.tsx`: admin copilot dashboard (`/admin/copilot`) — Overview/Usage/Providers/Learning/Observability
* `/client/src/components/copilot/*`: provider, app context, approval card, settings card, actions
* `/client/src/hooks/useCopilotProviderConfig.ts`: settings hook for provider/model/BYOK config
* `/scripts/verify-openrouter-free.mjs`: manual operator check for free OpenRouter tool-calling
* `/scripts/verify-codex-tools.mjs`: manual operator check for whether Codex honors the tools array

See the [In-App AI Copilot](in-app-copilot.mdx) page for behavior, trust model, and security.

## Agent Bridge Plugin

* `/plugins/dealdash-agent-bridge/.codex-plugin/plugin.json`: plugin manifest
* `/plugins/dealdash-agent-bridge/.mcp.json`: MCP server registration
* `/plugins/dealdash-agent-bridge/scripts/server.ts`: MCP stdio server
* `/plugins/dealdash-agent-bridge/scripts/lib/client.ts`: `/api/agent/*` client
* `/plugins/dealdash-agent-bridge/scripts/lib/media.ts`: photo upload and URL capture helpers
* `/plugins/dealdash-agent-bridge/skills/dealdash-agent-bridge/SKILL.md`: agent-facing usage guide

## Standalone drdj.me Shortener Plugin

* `/plugins/drdj-shortener/.mcp.json`: MCP server registration
* `/plugins/drdj-shortener/scripts/server.ts`: shortener-only MCP stdio server
* `/plugins/drdj-shortener/skills/drdj-shortener/SKILL.md`: tiny agent-facing shortener guide

Use this plugin when agents only need URL/photo short links or stats.

## Navigation Rule

Before editing, locate blast radius across:

* API route file
* schema/model definitions
* frontend consumers
* tests
* docs pages