classroomio/packages/core

@cio/core — shared business services

This package holds the business-logic layer that both apps/api (HTTP) and apps/jobs (BullMQ worker) need to call. Anything in here is transport-agnostic: no Hono Context, no ContentfulStatusCode, no c.json, no zValidator middleware. Just functions that compose database queries, apply business rules, and raise AppError on failure.

The name is intentional: this is the core of the platform. The HTTP routes in apps/api and the worker processors in apps/jobs are thin transports over this layer. Anything they share has to live here — otherwise one app ends up depending on the other (apps/jobs → apps/api was the original sin that motivated extracting this package).

What lives here

Folder	Contents
src/services/agent	The durable agent runner, chat-mode tool implementations, planning helpers.
src/services/course	Course / section / content / landing-page business logic.
src/services/exercise	Exercise + question CRUD and orchestration.
src/services/lesson	Lesson read/write helpers.
src/services/assets	Asset upload, attach, detach, presign — used by both API routes and worker.
src/services/jobs	BullMQ enqueue helpers (e.g. startMediaJob) callable from any service.
src/services/lesson-language	Localized lesson content helpers.
src/utils	Storage, presigning, sanitization, tinybird, redis helpers.
src/config	Env schema (env), storage config, dashboard URL helpers.

Placement rule

            ┌─────────────────────────────────────────────────────┐
            │  Does the function need a Hono Context, or call     │
            │  `c.json`, or validate a request shape?             │
            │                                                     │
            │      YES  →  it's a route handler, stays in         │
            │              `apps/api/src/routes/{domain}/…`       │
            │                                                     │
            │      NO   →  it's a business service, goes in       │
            │              `packages/core/src/services/{domain}/…`│
            └─────────────────────────────────────────────────────┘

If the function only touches the database and has no business logic, it doesn't belong here either — it goes in packages/db/src/queries/{domain}/. The split is:

• Query layer (@cio/db/queries): pure SQL/Drizzle helpers, no business rules.
• Service layer (@cio/core/services): composes queries, applies rules, throws AppError.
• Route layer (apps/api/src/routes): HTTP transport — auth, validation, status codes, response shapes.
• Worker layer (apps/jobs/src/workers): BullMQ transport — pulls a job, calls services, persists outcome.

What does NOT belong here

• HTTP-shaped code (Hono types, response helpers, content-type handling) — keep in apps/api.
• BullMQ worker bootstrapping (Redis connection, worker lifecycle) — keep in apps/jobs.
• Frontend / Svelte / UI primitives — those live in apps/dashboard or packages/ui.
• Raw Drizzle query functions with no business logic — those go in packages/db/queries.

Why it isn't called @cio/services

@cio/core is shorter and reads cleaner at import sites (from '@cio/core/services/course/content'). The folder structure makes it obvious that it's a services layer; the package name doesn't need to repeat that.

History

This package was originally extracted as @cio/agent-runtime to hold the durable agent runner and its transitive closure. That closure turned out to be ~80% generic business services that apps/api and the worker both need, so the package was renamed to @cio/core to match its contents. The agent runner (services/agent/course-generation-runner.ts) remains the top-level export for apps/jobs, but it's just one of many services living here now.