
airbot-backend
Backend architecture, Kotlin coroutines, and SQL/DAO rubrics for AIRBot reviews.
- version
- 0.1.0
Install
/plugin install airbot-backend@airbot-reviewersRun it inside Claude Code after adding the marketplace with /plugin marketplace add sids/airbot.
Contents
Discovered from sourceSkills 3
Mission
- Keep backend services modular: resources handle transport, managers own business logic, and data access stays isolated.
- Maintain clean dependency flow across modules (
service→core→models) to encourage reuse and testability.
Layering Principles
- Resources: Only translate HTTP/storage inputs to domain calls. No database or cross-service logic. Convert
SecurityContextearly. - Managers: Encapsulate business rules; coordinate helpers, other managers, workflows, and DAL components. Break cycles by separating read/write responsibilities or introducing controllers.
- Helpers/Services: Reusable integrations (feature flags, external clients). Centralize external service calls to simplify retries and upgrades.
- Repos/DAL/DAO: Keep database interactions single-purpose. Compose multi-step transactions in repos/DAL; keep DAO calls single query.
- Utils/Validators/Transformers: Pure functions and extensions only; avoid hidden state.
- Cache Managers: Inject Redis/Lettuce clients, expose typed
get/invalidatehelpers.
Package & Module Structure
- Enforce lowercase package names without underscores; avoid versioned package hierarchies (
v2folders). Prefermanagers.slotsovermanagers.slots.v2. - Organize by responsibility:
managers,helpers,utils,dao,workflows, etc. Mirror structure in tests. - Module boundaries:
core: managers, helpers, data access, transient models. May depend onmodels.service: Dropwizard resources, configuration, application wiring; no direct DB access.console-service: Console-specific resources/auth; depends oncore.client: Outbound clients; depend only onmodels.models: Shared API/data contracts; no dependencies.
Dependency Injection & Config
- Add new Redis/Cosmos/DB configs across all environments (
db-test,db-dev,db-warehouse-prod) and run the service locally to validate. - Annotate injectable classes with
@Singletonwhen appropriate. - Only use
@Namedwhen multiple bindings of the same type exist; otherwise default bindings suffice. - Centralize client construction in DI modules to enforce consistent timeouts and hosts.
Review Checklist
- Check that new features land in the correct layer and module (e.g., resources calling managers, not DAOs).
- Ensure helpers/managers do not introduce cyclic dependencies; suggest splitting read/write flows or using controller orchestrators.
- Verify repos/DAL enforce validation and error translation before returning data.
- Confirm new package or module names remain lowercase and idiomatic; flag attempts to create
v2package forks. - Audit DI modules for duplicate provider methods and proper scoping.
Tooling Tips
Globfor*.ktwithinservice/orcore/to inspect layer usage.ReadDI modules when new bindings appear to ensure wiring matches guidelines.Grepfor@Namedor direct DAO usage inside resources to catch misplaced logic.
Mission
- Preserve non-blocking performance characteristics by enforcing clear coroutine boundaries.
- Prevent thread pool exhaustion, deadlocks, and latency spikes caused by mixing blocking and suspend flows.
Red Flags
- Mixing blocking and suspending calls inside the same function without isolating the blocking work.
- Calling
runBlockinganywhere other than top-level entrypoints (resources,main) or when explicitly bridging to blocking code with the correct dispatcher. - Using
async { ... }.await()immediately, or usingasyncjust to change dispatchers. - Wiring
AsyncResponse(Dropwizard) to wrap blocking DAO calls instead of true suspend flows.
Review Checklist
- Verify suspending chains remain suspend: bubble
suspendup through managers/resources or wrap legacy blocking code withwithContext(Dispatchers.IO). - Ensure blocking functions stay blocking all the way up the call stack; prefer dedicated blocking helpers (e.g.,
getUserBlocking) rather than ad-hocrunBlocking. - When bridging to suspend from non-suspend contexts, check the dispatcher passed to
runBlockingmatches the underlying workload (usuallyDispatchers.IO). - Confirm
AsyncResponseis only applied to non-blocking suspend flows (Cosmos, service clients withawait/executeAwait). Flag usages that simply wrap JDBI or other blocking calls. - Look for nested coroutine builders. Replace
async/awaitpairs used sequentially with direct calls; use concurrentasynconly when awaiting later. - Ensure dispatcher changes use
withContext, notasync, and that blocking calls inside suspend functions are guarded with the appropriate context.
Tooling Tips
GrepforrunBlocking,.await(),executeSync, orAsyncResponseto inspect how coroutines and blocking APIs mix.Readaffected managers/resources to trace whether suspend functions bubble correctly.Globmodules like*Manager.kt,*Resource.kt, and*Dao.ktwhen you need broader context about call chains.
Mission
- Guard database performance and correctness by enforcing disciplined DAO/DAL patterns.
- Catch regressions that risk outages: unbounded queries, missing indexes, unsafe scripts, or misuse of replicas.
Query Execution Standards
- Require explicit column selection (
SELECT col1, col2) rather thanSELECT *. - Prefer synchronous flows within
jdbi.inTransaction {}; avoid mixing suspend calls inside transactions. - Enforce batching (
@SqlBatch,@BatchChunkSize(2000)) for bulk inserts/updates and chunk largeWHERE INarguments (SQL Server limit ~2200 params). - Validate pagination on read-heavy endpoints; flag unbounded fetches or N+1 loops.
- Ensure blocking annotations (
@BlockingClass,@BlockingCall) exist for DAL/Repo classes and consumers. - Confirm master vs. replica usage: critical writes/reads hit master; replica lag can reach 30 minutes.
Indexing & Performance
- Request evidence of supporting indexes for new predicates, sort columns, and pagination keys.
- Encourage use of table aliases/prefixes in JOINs to maintain clarity.
- For new queries, verify index coverage and that
updated_attimestamps update alongside data mutations. - Demand UTC handling for timestamps and rely on the database (
CURRENT_TIMESTAMP) to set them.
Schema & DDL Expectations
- Ensure PRs document DDL changes and keep migrations incremental/backward compatible.
- Require
created_at/updated_atcolumns, primary keys, and consider unique constraints where appropriate. - Prefer
NVARCHARoverVARCHAR; align column nullability with Kotlin model nullability. - Advocate for foreign keys to avoid orphaned rows and use online/resumable index operations.
Scripts & Data Ops
- Scripts should live in dedicated packages, run transactional logic in managers/DAL, and treat CLI entrypoints as thin wrappers.
- Verify bulk update scripts log progress, support
mockRun, wrap per-row mutations in try/catch, and notify stakeholders before production runs.
Related Stores
- Cosmos DB batches should rely on
BulkExecutor; discourage ad-hoc parallel loops. - RedisCache2 usage must reuse clients, keep TTLs under 6 hours, and avoid local caches that cannot be invalidated.
Tooling Tips
GrepforSELECT *,@SqlBatch,inTransaction, orAsyncResponseinside DAO code to ensure patterns align.Readmigration files and DAL implementations to confirm pagination, batching, and index handling.Glob*Dao.kt,*Repository.kt,*Script.ktto review related data access or scripting changes together.
Sponsors
Details
- Marketplace
- sids/airbot
- Source
- plugins/airbot-backend
- Author
- AIRBot Maintainers
- Category
- Community