@ftisindia/create-app 0.1.0

package/template/src/modules/organisations/application/services/organisations.service.ts

@@ -0,0 +1,147 @@
+import { ConflictException, Injectable } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
+import { CreateOrganisationDto } from "../../dto/create-organisation.dto";
+import { OrganisationsRepository } from "../../infrastructure/repositories/organisations.repository";
+import {
+  defaultOrganisationRoles,
+  defaultOrganisationSettings,
+} from "../../types/default-organisation-data";
+
+@Injectable()
+export class OrganisationsService {
+  constructor(
+    private readonly organisationsRepository: OrganisationsRepository,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async createOrganisation(
+    currentUser: AuthenticatedUser,
+    dto: CreateOrganisationDto,
+  ) {
+    const name = dto.name.trim();
+    const slug = dto.slug?.trim() || (await this.createAvailableSlug(name));
+
+    if (dto.slug && (await this.organisationsRepository.findBySlug(slug))) {
+      throw new ConflictException("Organisation slug is already in use.");
+    }
+
+    try {
+      return await this.prisma.$transaction(async (tx) => {
+        const organisation = await this.organisationsRepository.create(
+          {
+            name,
+            slug,
+          },
+          tx,
+        );
+
+        const roles = await Promise.all(
+          defaultOrganisationRoles.map((roleName) =>
+            tx.role.create({
+              data: {
+                orgId: organisation.id,
+                name: roleName,
+                isSystemSeeded: true,
+              },
+            }),
+          ),
+        );
+        const ownerRole = roles.find((role) => role.name === "Owner");
+
+        if (!ownerRole) {
+          throw new Error("Owner role was not seeded.");
+        }
+
+        const membership = await tx.membership.create({
+          data: {
+            userId: currentUser.id,
+            orgId: organisation.id,
+            roleId: ownerRole.id,
+            isOwner: true,
+            isBillingContact: true,
+          },
+        });
+
+        const settings = await Promise.all(
+          defaultOrganisationSettings.map((setting) =>
+            tx.organisationSetting.create({
+              data: {
+                orgId: organisation.id,
+                key: setting.key,
+                value: setting.value,
+              },
+            }),
+          ),
+        );
+
+        await tx.auditLog.create({
+          data: {
+            orgId: organisation.id,
+            actorUserId: currentUser.id,
+            action: "organisation.create",
+            targetType: "Organisation",
+            targetId: organisation.id,
+            metadata: {
+              name: organisation.name,
+              slug: organisation.slug,
+              defaultRoles: roles.map((role) => role.name),
+              defaultSettings: settings.map((setting) => setting.key),
+            },
+          },
+        });
+
+        return {
+          organisation,
+          membership,
+          roles: roles.map((role) => ({
+            id: role.id,
+            name: role.name,
+            isSystemSeeded: role.isSystemSeeded,
+          })),
+          settings: settings.map((setting) => ({
+            key: setting.key,
+            value: setting.value,
+          })),
+        };
+      });
+    } catch (error) {
+      if (isPrismaUniqueError(error)) {
+        throw new ConflictException("Organisation slug is already in use.");
+      }
+
+      throw error;
+    }
+  }
+
+  private async createAvailableSlug(name: string) {
+    const base = slugify(name);
+    let candidate = base;
+    let suffix = 2;
+
+    while (await this.organisationsRepository.findBySlug(candidate)) {
+      candidate = `${base}-${suffix}`;
+      suffix += 1;
+    }
+
+    return candidate;
+  }
+}
+
+function isPrismaUniqueError(error: unknown) {
+  return (
+    error instanceof Prisma.PrismaClientKnownRequestError &&
+    error.code === "P2002"
+  );
+}
+
+function slugify(value: string) {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || `org-${Date.now()}`;
+}

package/template/src/modules/organisations/dto/create-organisation.dto.ts

@@ -0,0 +1,32 @@
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import {
+  IsOptional,
+  IsString,
+  Matches,
+  MaxLength,
+  MinLength,
+} from "class-validator";
+
+export class CreateOrganisationDto {
+  @ApiProperty({ example: "Acme Operations", minLength: 2, maxLength: 120 })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(120)
+  name!: string;
+
+  @ApiPropertyOptional({
+    description:
+      "Optional URL-friendly slug. Generated from the name when omitted.",
+    example: "acme-operations",
+    minLength: 2,
+    maxLength: 80,
+  })
+  @IsOptional()
+  @IsString()
+  @MinLength(2)
+  @MaxLength(80)
+  @Matches(/^[a-z0-9][a-z0-9-]*$/, {
+    message: "slug must contain lowercase letters, numbers, and hyphens only",
+  })
+  slug?: string;
+}

package/template/src/modules/organisations/dto/organisation-response.dto.ts

@@ -0,0 +1,62 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { OrganisationStatus } from "@prisma/client";
+import { MembershipResponseDto } from "../../../common/dto/membership-response.dto";
+
+export class OrganisationResponseDto {
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({ example: "Acme Operations" })
+  name!: string;
+
+  @ApiProperty({ example: "acme-operations" })
+  slug!: string;
+
+  @ApiProperty({ enum: OrganisationStatus, example: OrganisationStatus.ACTIVE })
+  status!: OrganisationStatus;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  createdAt!: string;
+
+  @ApiProperty({ example: "2026-06-01T10:30:00.000Z", format: "date-time" })
+  updatedAt!: string;
+}
+
+class SeededOrganisationRoleDto {
+  @ApiProperty({
+    example: "f602c057-04f4-4ef8-8c84-1b7c62fbf8c5",
+    format: "uuid",
+  })
+  id!: string;
+
+  @ApiProperty({ example: "Owner" })
+  name!: string;
+
+  @ApiProperty({ example: true })
+  isSystemSeeded!: boolean;
+}
+
+class SeededOrganisationSettingDto {
+  @ApiProperty({ example: "timezone" })
+  key!: string;
+
+  @ApiProperty({ example: "UTC" })
+  value!: unknown;
+}
+
+export class CreateOrganisationResponseDto {
+  @ApiProperty({ type: OrganisationResponseDto })
+  organisation!: OrganisationResponseDto;
+
+  @ApiProperty({ type: MembershipResponseDto })
+  membership!: MembershipResponseDto;
+
+  @ApiProperty({ type: [SeededOrganisationRoleDto] })
+  roles!: SeededOrganisationRoleDto[];
+
+  @ApiProperty({ type: [SeededOrganisationSettingDto] })
+  settings!: SeededOrganisationSettingDto[];
+}

package/template/src/modules/organisations/infrastructure/repositories/organisations.repository.ts

@@ -0,0 +1,24 @@
+import { Injectable } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+
+type PrismaClientLike = Prisma.TransactionClient | PrismaService;
+
+@Injectable()
+export class OrganisationsRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  findBySlug(slug: string, client: PrismaClientLike = this.prisma) {
+    return client.organisation.findUnique({
+      where: { slug },
+      select: { id: true },
+    });
+  }
+
+  create(
+    data: Prisma.OrganisationCreateInput,
+    client: PrismaClientLike = this.prisma,
+  ) {
+    return client.organisation.create({ data });
+  }
+}

package/template/src/modules/organisations/organisations.module.ts

@@ -0,0 +1,12 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module";
+import { OrganisationsService } from "./application/services/organisations.service";
+import { OrganisationsRepository } from "./infrastructure/repositories/organisations.repository";
+import { OrganisationsController } from "./presentation/organisations.controller";
+
+@Module({
+  imports: [AuthModule],
+  controllers: [OrganisationsController],
+  providers: [OrganisationsRepository, OrganisationsService],
+})
+export class OrganisationsModule {}

package/template/src/modules/organisations/presentation/organisations.controller.ts

@@ -0,0 +1,37 @@
+import { Body, Controller, Post, UseGuards } from "@nestjs/common";
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOperation,
+  ApiTags,
+} from "@nestjs/swagger";
+import { ApiErrorResponses } from "../../../common/swagger/api-error-responses";
+import { JwtAuthGuard } from "../../auth/infrastructure/passport/jwt-auth.guard";
+import { CurrentUser } from "../../auth/presentation/current-user.decorator";
+import { AuthenticatedUser } from "../../auth/types/authenticated-user";
+import { OrganisationsService } from "../application/services/organisations.service";
+import { CreateOrganisationDto } from "../dto/create-organisation.dto";
+import { CreateOrganisationResponseDto } from "../dto/organisation-response.dto";
+
+@ApiTags("Organisations")
+@ApiBearerAuth()
+@Controller("organisations")
+export class OrganisationsController {
+  constructor(private readonly organisationsService: OrganisationsService) {}
+
+  @Post()
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: "Create an organisation for the current user." })
+  @ApiCreatedResponse({
+    description:
+      "Organisation created with default roles, settings, and owner membership.",
+    type: CreateOrganisationResponseDto,
+  })
+  @ApiErrorResponses(400, 401, 409)
+  create(
+    @CurrentUser() user: AuthenticatedUser,
+    @Body() dto: CreateOrganisationDto,
+  ) {
+    return this.organisationsService.createOrganisation(user, dto);
+  }
+}

package/template/src/modules/organisations/types/default-organisation-data.ts

@@ -0,0 +1,18 @@
+import { Prisma } from "@prisma/client";
+import { settingDefinitions } from "../../settings/types/setting-definitions";
+
+export const defaultOrganisationRoles = [
+  "Owner",
+  "Admin",
+  "Manager",
+  "Staff",
+  "Viewer",
+] as const;
+
+export const defaultOrganisationSettings: Array<{
+  key: string;
+  value: Prisma.InputJsonValue;
+}> = Object.entries(settingDefinitions).map(([key, definition]) => ({
+  key,
+  value: definition.defaultValue,
+}));

package/template/src/modules/platform-admin/.gitkeep

@@ -0,0 +1 @@
+# keep

package/template/src/modules/request-context/application/services/request-context.service.ts

@@ -0,0 +1,79 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { randomUUID } from "crypto";
+import { ForbiddenException, Injectable } from "@nestjs/common";
+import { RequestContext } from "../../types/request-context";
+
+@Injectable()
+export class RequestContextService {
+  private readonly storage = new AsyncLocalStorage<RequestContext>();
+
+  run<T>(context: Partial<RequestContext>, callback: () => T): T {
+    return this.storage.run(
+      {
+        requestId: context.requestId ?? randomUUID(),
+        source: context.source ?? "worker",
+        startedAt: context.startedAt ?? new Date(),
+        ...context,
+      },
+      callback,
+    );
+  }
+
+  get() {
+    return this.storage.getStore();
+  }
+
+  getRequestId() {
+    return this.get()?.requestId;
+  }
+
+  getUserId() {
+    return this.get()?.userId;
+  }
+
+  getOrgId() {
+    return this.get()?.orgId;
+  }
+
+  getMembership() {
+    return this.get()?.rbac;
+  }
+
+  getRbacContext() {
+    return this.get()?.rbac;
+  }
+
+  getMembershipId() {
+    return this.get()?.rbac?.membershipId;
+  }
+
+  getRoleId() {
+    return this.get()?.rbac?.roleId;
+  }
+
+  getPermissions() {
+    return this.get()?.rbac?.permissionKeys ?? [];
+  }
+
+  merge(patch: Partial<RequestContext>) {
+    const context = this.storage.getStore();
+    if (!context) {
+      return;
+    }
+
+    Object.assign(context, patch);
+  }
+
+  assertOrgScope(orgId: string) {
+    const activeOrgId = this.getOrgId();
+    if (!activeOrgId) {
+      throw new ForbiddenException("Active organisation context is required.");
+    }
+
+    if (activeOrgId !== orgId) {
+      throw new ForbiddenException(
+        "Request organisation context does not match the requested resource.",
+      );
+    }
+  }
+}

package/template/src/modules/request-context/presentation/org-scope.guard.ts

@@ -0,0 +1,26 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from "@nestjs/common";
+import { RequestContextService } from "../application/services/request-context.service";
+import { RequestWithContext } from "../types/request-context";
+
+@Injectable()
+export class OrgScopeGuard implements CanActivate {
+  constructor(private readonly requestContext: RequestContextService) {}
+
+  canActivate(context: ExecutionContext) {
+    const request = context.switchToHttp().getRequest<RequestWithContext>();
+    const orgId = request.params?.orgId;
+
+    if (!orgId) {
+      throw new ForbiddenException("Organisation context is required.");
+    }
+
+    request.orgId = orgId;
+    this.requestContext.merge({ orgId });
+    return true;
+  }
+}

package/template/src/modules/request-context/presentation/request-context.interceptor.ts

@@ -0,0 +1,26 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from "@nestjs/common";
+import { Observable } from "rxjs";
+import { RequestContextService } from "../application/services/request-context.service";
+import { RequestWithContext } from "../types/request-context";
+
+@Injectable()
+export class RequestContextInterceptor implements NestInterceptor {
+  constructor(private readonly requestContext: RequestContextService) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const request = context.switchToHttp().getRequest<RequestWithContext>();
+
+    this.requestContext.merge({
+      userId: request.user?.id,
+      orgId: request.orgId ?? request.params?.orgId,
+      rbac: request.rbac,
+    });
+
+    return next.handle();
+  }
+}

package/template/src/modules/request-context/presentation/request-context.middleware.ts

@@ -0,0 +1,31 @@
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import { randomUUID } from "crypto";
+import { RequestContextService } from "../application/services/request-context.service";
+import { RequestWithContext } from "../types/request-context";
+
+@Injectable()
+export class RequestContextMiddleware implements NestMiddleware {
+  constructor(private readonly requestContext: RequestContextService) {}
+
+  use(request: RequestWithContext, _response: unknown, next: () => void) {
+    const requestId =
+      headerAsString(request.headers?.["x-request-id"]) || randomUUID();
+
+    this.requestContext.run(
+      {
+        requestId,
+        source: "http",
+        startedAt: new Date(),
+        method: request.method,
+        path: request.originalUrl ?? request.url,
+        ipAddress: request.ip,
+        userAgent: headerAsString(request.headers?.["user-agent"]),
+      },
+      next,
+    );
+  }
+}
+
+function headerAsString(value: string | string[] | undefined) {
+  return Array.isArray(value) ? value[0] : value;
+}

package/template/src/modules/request-context/request-context.module.ts

@@ -0,0 +1,25 @@
+import { Global, MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { RequestContextService } from "./application/services/request-context.service";
+import { OrgScopeGuard } from "./presentation/org-scope.guard";
+import { RequestContextInterceptor } from "./presentation/request-context.interceptor";
+import { RequestContextMiddleware } from "./presentation/request-context.middleware";
+
+@Global()
+@Module({
+  providers: [
+    OrgScopeGuard,
+    RequestContextMiddleware,
+    RequestContextService,
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: RequestContextInterceptor,
+    },
+  ],
+  exports: [OrgScopeGuard, RequestContextService],
+})
+export class RequestContextModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RequestContextMiddleware).forRoutes("*");
+  }
+}

package/template/src/modules/request-context/types/request-context.ts

@@ -0,0 +1,29 @@
+import { RbacContext } from "../../access-control/types/rbac-context";
+
+export type RequestSource = "http" | "worker";
+
+export type RequestContext = {
+  requestId: string;
+  source: RequestSource;
+  startedAt: Date;
+  method?: string;
+  path?: string;
+  ipAddress?: string;
+  userAgent?: string;
+  userId?: string;
+  orgId?: string;
+  rbac?: RbacContext;
+  jobId?: string;
+};
+
+export type RequestWithContext = {
+  headers?: Record<string, string | string[] | undefined>;
+  ip?: string;
+  method?: string;
+  orgId?: string;
+  originalUrl?: string;
+  params?: Record<string, string | undefined>;
+  rbac?: RbacContext;
+  url?: string;
+  user?: { id: string };
+};

package/template/src/modules/sample/application/services/sample.service.ts

@@ -0,0 +1,67 @@
+import { Injectable } from "@nestjs/common";
+import { Prisma } from "@prisma/client";
+import { PrismaService } from "../../../../database/prisma/prisma.service";
+import { AuthenticatedUser } from "../../../auth/types/authenticated-user";
+import { RequestContextService } from "../../../request-context/application/services/request-context.service";
+import { SampleEchoDto } from "../../dto/sample-echo.dto";
+
+@Injectable()
+export class SampleService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  getStatus(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+
+    return {
+      ok: true,
+      orgId,
+      contextOrgId: this.requestContext.getOrgId(),
+      requestId: this.requestContext.getRequestId(),
+    };
+  }
+
+  async echo(user: AuthenticatedUser, orgId: string, dto: SampleEchoDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const message = dto.message.trim();
+
+    await this.writeAudit({
+      orgId,
+      actorUserId: user.id,
+      action: "sample.echo",
+      targetId: orgId,
+      metadata: {
+        messageLength: message.length,
+        requestId: this.requestContext.getRequestId(),
+      },
+    });
+
+    return {
+      orgId,
+      contextOrgId: this.requestContext.getOrgId(),
+      message,
+      requestId: this.requestContext.getRequestId(),
+    };
+  }
+
+  private async writeAudit(data: {
+    orgId: string;
+    actorUserId: string;
+    action: string;
+    targetId: string;
+    metadata?: Prisma.InputJsonObject;
+  }) {
+    await this.prisma.auditLog.create({
+      data: {
+        orgId: data.orgId,
+        actorUserId: data.actorUserId,
+        action: data.action,
+        targetType: "Sample",
+        targetId: data.targetId,
+        metadata: data.metadata,
+      },
+    });
+  }
+}

package/template/src/modules/sample/dto/sample-echo.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MaxLength, MinLength } from "class-validator";
+
+export class SampleEchoDto {
+  @ApiProperty({ example: "Hello from the sample module." })
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  message!: string;
+}

package/template/src/modules/sample/dto/sample-response.dto.ts

@@ -0,0 +1,41 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class SampleStatusResponseDto {
+  @ApiProperty({ example: true })
+  ok!: boolean;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  contextOrgId!: string;
+
+  @ApiProperty({ example: "req_01HZX3J8TBMJAEK42S7XK4V7C8" })
+  requestId!: string;
+}
+
+export class SampleEchoResponseDto {
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  orgId!: string;
+
+  @ApiProperty({
+    example: "2c67399d-670c-4025-a5fd-1ea9a211891e",
+    format: "uuid",
+  })
+  contextOrgId!: string;
+
+  @ApiProperty({ example: "Hello from the sample module." })
+  message!: string;
+
+  @ApiProperty({ example: "req_01HZX3J8TBMJAEK42S7XK4V7C8" })
+  requestId!: string;
+}