chatbotx-basecode

name: chatbotx-basecode description: >- Understand and audit the ChatbotX base code before making changes. Use when asked to scan the project, check architecture, locate ownership boundaries, onboard to the repository, or decide which project-specific skill should handle a task.

ChatbotX Basecode

Use this skill as the first pass for broad or ambiguous requests. It is a map, not a replacement for reading adjacent code.

Project Shape

ChatbotX is a pnpm workspace + Turborepo monorepo.

apps/
  builder/     Next.js app: product UI, oRPC/OpenAPI, route handlers
  worker/      BullMQ/Kafka background jobs
  realtime/    PartyKit realtime server
  cli/         chatbotx-cli
  mcp-server/  MCP tools generated from OpenAPI

packages/
  business/       service layer and business orchestration
  database/       Drizzle schema, relations, repositories, migrations
  ui/             shared UI components
  public-apis/    typed public API client
  sdk/            integration contracts and shared schemas
  worker-config/  queue names, job payloads, BullMQ queues
  flow-config/    flow/node/step config schemas
  ai, events, redis, kafka, filesystem, mail, imports, analytics, ...

integrations/
  messenger, whatsapp, zalo, tiktok, telegram, webchat, smtp, openai, google-sheets, ...

Skill Router

• Builder feature, page, action, query, or public route: use feature-scaffold.
• oRPC or OpenAPI endpoint: use orpc-api.
• Database schema, relations, migration, repository: use drizzle-database.
• Service layer, app data-access boundary: use business-data-access.
• UI component work, forms, tables, translations: use builder-ui-i18n.
• Worker, BullMQ, Kafka, scheduled job: use worker-development.
• Channel integration or webhook behavior: use integration-channel.
• Flow step or state-based routing: use flow-step-development.
• CLI, MCP server, generated public client: use public-api-tooling.
• Dev server, build, lint, package management: use turborepo-workflow.

Basecode Scan Checklist

1. Read the nearest package.json, route/module files, and sibling features.
2. Identify the owning layer before editing:
   • UI/app orchestration: apps/builder
   • business rules: packages/business
   • raw database queries: packages/database/src/repositories
   • schema/migrations: packages/database
   • async processing: apps/worker + packages/worker-config
   • external channel protocol: integrations/<channel>
3. Search for a similar feature and mirror naming, imports, error handling, and tests.
4. Check .agents/rules/* for local invariants, especially data access and git.
5. Keep changes scoped to the user request; do not refactor legacy exceptions unless required.

Non-Negotiable Invariants

• New app/integration code must not import db from @chatbotx.io/database/client.
• User-facing builder strings must use useTranslations() and message JSON keys.
• Next.js app pages use Promise params / searchParams.
• Public unauthenticated builder routes must be registered in apps/builder/src/proxy.ts.
• Middleware names intentionally contain three ds: workspaceAuthorizedMidddleware and workspaceTokenAuthMidddleware.
• Adding database tables requires schema, migration, relation import, and relation spread.
• Adding ChannelType values requires fixing every Record<ChannelType, ...> use.

Validation

Prefer targeted checks first, then broader checks when the blast radius grows:

pnpm --filter builder check-types
pnpm --filter @chatbotx.io/database check-types
pnpm --filter worker test
pnpm lint
pnpm build

If the exact script is unclear, inspect the relevant workspace package.json.