| 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
- Read the nearest
package.json, route/module files, and sibling features.
- 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>
- Search for a similar feature and mirror naming, imports, error handling, and tests.
- Check
.agents/rules/* for local invariants, especially data access and git.
- 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.
