Architecture

The Naalya backend is a NestJS monorepo: several apps in one repository, sharing one set of dependencies and one pile of common code. The split exists because not all work is request work — answering HTTP should be fast, while email, audit writes, and external syncs are slow and retryable, so they run in separate processes.

Three things to hold in your head:

• server — the HTTP API that answers the frontend.
• worker and audit — background processes, no HTTP, just jobs off a queue.
• libs/shared (imported as @app/shared) — code all three reuse.

Repo layout

apps/
  server/   → the HTTP API
  worker/   → background job processor
  audit/    → audit-log microservice
libs/
  shared/   → code shared across all apps (@app/shared)
database/
  migrations/   → TypeORM migrations (root-level, app-agnostic)
emails/         → React Email templates

Each app is self-contained, with its own main.ts and root module. Apps never import each other — the only shared code comes through @app/shared.

What the apps talk to

Four backing services, and in development only two of them are on your machine — see Getting Started for the split.

There is also a type bus: the server publishes shared TypeScript types at /.well-known/chowbea.json, which the Education Hub generates from. Types that never appear on a REST body — websocket payloads, domain enums — cross there instead of through Swagger. See How Chowbea works.

The three apps

server — Express 5 HTTP server. Its root module apps/server/src/app/app.module.ts wires the database, the Redis/BullMQ connection, and one feature module per domain. You add a feature module and register it here; you rarely edit app.module.ts directly. Every route sits under api/v1 (so a users route is /api/v1/users) — the lone exception is /queues*, excluded so the Bull Board dashboard stays mounted at /queues.

worker is more than a queue consumer. Alongside its BullMQ processors it hosts naalya-agent/ — the LangGraph graph behind Rover and the role subagents — which reaches school data by calling back into the server over RabbitMQ rather than touching the database itself. That seam is the whole security model: How the AI system works.

audit is the simple one: a NestJS app with no HTTP server consuming one queue. It runs in its own process for isolation, so writing audit records never slows an API request. How the queues work → Queues & Messaging.

libs/shared

@app/shared is exposed through one barrel file (libs/shared/src/index.ts). Import from the package name, never a deep path:

import { BaseRepository, UserType, generateSlug } from '@app/shared';

Path aliases

Defined in tsconfig.json (and mirrored in the Vitest configs). Use them before reaching for a relative ../ chain.

"paths": {
  "@app/shared": ["libs/shared/src"],
  "@app/shared/*": ["libs/shared/src/*"],
  "@server/*": ["apps/server/src/*"],
  "@worker/*": ["apps/worker/src/*"]
}

Rule of thumb: @app/shared for anything reused across apps, @server/* for paths inside the server app.

Request lifecycle

A request to the server app passes through a fixed assembly line before reaching your handler. Order is set in main.ts (middleware, pipe, interceptor, filter) and auth.module.ts (guards).

HTTP request
  ▼  Express middleware  (permissionScope → tenantContext → requestId → cookieParser)
  ▼  Global guards       (JwtAuthGuard → UserTypeGuard → SystemRoleGuard → PermissionsGuard)
  ▼  ValidationPipe      (validate + transform the DTO)
  ▼  Controller handler  (your code)
  ▼  LoggingInterceptor  (wraps the response)
  ▼  Exception filters   (only if something threw)
  ▼  HTTP response

Where to go next