sids avatar

airbot-backend

Backend architecture, Kotlin coroutines, and SQL/DAO rubrics for AIRBot reviews.

version
0.1.0

Install

/plugin install airbot-backend@airbot-reviewers

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sids/airbot.

Contents

Discovered from source

Skills 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 SecurityContext early.
  • 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/invalidate helpers.

Package & Module Structure

  • Enforce lowercase package names without underscores; avoid versioned package hierarchies (v2 folders). Prefer managers.slots over managers.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 on models.
    • service: Dropwizard resources, configuration, application wiring; no direct DB access.
    • console-service: Console-specific resources/auth; depends on core.
    • client: Outbound clients; depend only on models.
    • 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 @Singleton when appropriate.
  • Only use @Named when 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 v2 package forks.
  • Audit DI modules for duplicate provider methods and proper scoping.

Tooling Tips

  • Glob for *.kt within service/ or core/ to inspect layer usage.
  • Read DI modules when new bindings appear to ensure wiring matches guidelines.
  • Grep for @Named or 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 runBlocking anywhere other than top-level entrypoints (resources, main) or when explicitly bridging to blocking code with the correct dispatcher.
  • Using async { ... }.await() immediately, or using async just to change dispatchers.
  • Wiring AsyncResponse (Dropwizard) to wrap blocking DAO calls instead of true suspend flows.

Review Checklist

  • Verify suspending chains remain suspend: bubble suspend up through managers/resources or wrap legacy blocking code with withContext(Dispatchers.IO).
  • Ensure blocking functions stay blocking all the way up the call stack; prefer dedicated blocking helpers (e.g., getUserBlocking) rather than ad-hoc runBlocking.
  • When bridging to suspend from non-suspend contexts, check the dispatcher passed to runBlocking matches the underlying workload (usually Dispatchers.IO).
  • Confirm AsyncResponse is only applied to non-blocking suspend flows (Cosmos, service clients with await/executeAwait). Flag usages that simply wrap JDBI or other blocking calls.
  • Look for nested coroutine builders. Replace async/await pairs used sequentially with direct calls; use concurrent async only when awaiting later.
  • Ensure dispatcher changes use withContext, not async, and that blocking calls inside suspend functions are guarded with the appropriate context.

Tooling Tips

  • Grep for runBlocking, .await(), executeSync, or AsyncResponse to inspect how coroutines and blocking APIs mix.
  • Read affected managers/resources to trace whether suspend functions bubble correctly.
  • Glob modules like *Manager.kt, *Resource.kt, and *Dao.kt when 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 than SELECT *.
  • Prefer synchronous flows within jdbi.inTransaction {}; avoid mixing suspend calls inside transactions.
  • Enforce batching (@SqlBatch, @BatchChunkSize(2000)) for bulk inserts/updates and chunk large WHERE IN arguments (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_at timestamps 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_at columns, primary keys, and consider unique constraints where appropriate.
  • Prefer NVARCHAR over VARCHAR; 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

  • Grep for SELECT *, @SqlBatch, inTransaction, or AsyncResponse inside DAO code to ensure patterns align.
  • Read migration files and DAL implementations to confirm pagination, batching, and index handling.
  • Glob *Dao.kt, *Repository.kt, *Script.kt to review related data access or scripting changes together.

Sponsors

Details

Marketplace
sids/airbot
Source
plugins/airbot-backend
Author
AIRBot Maintainers
Category
Community

More from sids/airbot

All 3