Modules

The 15 backend feature modules — where each one mounts, what it owns, and the route-ordering and scoping rules that are easy to get wrong.

The backend is 236 TypeScript files across 15 feature modules plus the app root. The global prefix is api, with /health explicitly excluded.

app.setGlobalPrefix("api", {
  exclude: [{ path: "health", method: RequestMethod.GET }],
});

The map

Two mounts that are not where you would look

TaskController is root-mounted. Its @Controller() decorator takes no prefix, so it declares both /api/tasks/* and /api/projects/:projectId/tasks from the same class. If you go looking for project tasks under src/project/, you will not find them there.

ProfileController is not its own module. It lives in src/auth/profile.controller.ts and mounts at /api/auth/user, so its routes sit a segment deeper than AuthController’s: /api/auth/user/profile, /api/auth/user/avatar-upload. Nothing collides with GET /api/auth/user — the paths are simply different.

Route declaration order matters

AssetController mounts GET logs above GET :id with a comment explaining why:

// NOTE: this MUST stay above @Get(':id'). Nest matches routes in declaration
// order, so a later literal path loses to an earlier parameterized one.
@Get("logs")
async getMyLogs(/* … */) {}

@Get(":id")
async getAssetById(/* … */) {}

Reorder those two and /api/assets/logs starts resolving as an asset whose ID is the literal string logs.

Transactional writes

Multi-step database writes go through QueryRunnerExec in src/shared/services/query-runner-exec.service.ts. Its commit and rollback always release the runner and are idempotent, so a double-rollback in an error path is safe.

Upload completion is the canonical example: asset, version, and log rows are persisted in a single transaction, so a failure never leaves a version row pointing at an asset that does not exist.

Custom exceptions

Throw ApplicationException from src/lib/exception/app.exception.ts for expected 4xx conditions. It is a bare Error subclass — services catch it and translate to the right Nest exception:

if (error instanceof ApplicationException)
  throw new NotFoundException(error.message);

this._logger.error((error as Error).message);
throw new InternalServerErrorException("Something went wrong");

Everything else reaches the global filter.

Scoping is not enforced by the compiler

Asset and collection reads and writes verify Asset → Collection → User == req.user and return 404 on mismatch, so a probe cannot distinguish “not yours” from “does not exist”.

Soft deletes do not cascade through joins

TypeORM’s soft-delete filter applies to the root entity of a query only. A leftJoinAndSelect/innerJoin to a related table carries no deleted_at IS NULL unless it is added by hand — and ProjectService.remove() soft-removes a project without cascading that delete to its tasks, so a task under a soft-deleted project stays a live row.

Four call sites independently discovered this and each added its own project.deleted_at IS NULL predicate: TaskService.list, TaskService.findOwnedWithManager, DashboardService.orgTasks, and ProfileService.stats. The same shape recurs one relation lower for loadRelationCountAndMap in ProjectService.countRelations (task and asset counts) and for the task.assets join in TaskService.findOwnedWithManager. See Workspace for the concrete routes this affects.