Add layered enterprise API architecture

Author: wbizmo

dist/templates/api/README.md

@@ -87,6 +87,38 @@ Send access tokens using:
 
 Never use the default JWT secrets in production.
 
+## Application Architecture
+
+The generated API uses a modular layered architecture:
+
+    src/
+      core/
+        errors/
+        http/
+        types/
+      modules/
+        auth/
+          auth.controller.ts
+          auth.repository.ts
+          auth.routes.ts
+          auth.schemas.ts
+          auth.service.ts
+          auth.types.ts
+        users/
+          user.controller.ts
+          user.dto.ts
+          user.repository.ts
+          user.service.ts
+
+Layer responsibilities:
+
+- Routes define HTTP endpoints and middleware.
+- Controllers translate HTTP requests into service calls.
+- Services contain application and domain logic.
+- Repositories isolate Prisma database access.
+- DTOs control data exposed by the API.
+- Core utilities provide shared errors, response envelopes, and pagination.
+
 ## Quality Commands
 
 Run tests:

dist/templates/api/src/core/errors/application-error.ts

@@ -0,0 +1,21 @@
+export type ApplicationErrorOptions = {
+  statusCode: number;
+  code: string;
+  message: string;
+  details?: unknown;
+};
+
+export class ApplicationError extends Error {
+  readonly statusCode: number;
+  readonly code: string;
+  readonly details?: unknown;
+
+  constructor(options: ApplicationErrorOptions) {
+    super(options.message);
+
+    this.name = "ApplicationError";
+    this.statusCode = options.statusCode;
+    this.code = options.code;
+    this.details = options.details;
+  }
+}

dist/templates/api/src/core/errors/error-codes.ts

@@ -0,0 +1,12 @@
+export const ErrorCode = {
+  ValidationFailed: "VALIDATION_FAILED",
+  AuthenticationRequired: "AUTHENTICATION_REQUIRED",
+  InvalidCredentials: "INVALID_CREDENTIALS",
+  ResourceNotFound: "RESOURCE_NOT_FOUND",
+  ResourceConflict: "RESOURCE_CONFLICT",
+  Forbidden: "FORBIDDEN",
+  InternalError: "INTERNAL_ERROR"
+} as const;
+
+export type ErrorCode =
+  (typeof ErrorCode)[keyof typeof ErrorCode];

dist/templates/api/src/core/http/api-response.ts

@@ -0,0 +1,18 @@
+export type ApiSuccessResponse<T> = {
+  data: T;
+  meta?: Record<string, unknown>;
+};
+
+export function successResponse<T>(
+  data: T,
+  meta?: Record<string, unknown>
+): ApiSuccessResponse<T> {
+  return meta
+    ? {
+        data,
+        meta
+      }
+    : {
+        data
+      };
+}

dist/templates/api/src/core/types/pagination.ts

@@ -0,0 +1,26 @@
+export type PaginationInput = {
+  page: number;
+  limit: number;
+};
+
+export type PaginationMeta = {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+};
+
+export function createPaginationMeta(
+  input: PaginationInput,
+  total: number
+): PaginationMeta {
+  return {
+    page: input.page,
+    limit: input.limit,
+    total,
+    totalPages:
+      total === 0
+        ? 0
+        : Math.ceil(total / input.limit)
+  };
+}

dist/templates/api/src/modules/auth/auth.controller.ts

@@ -0,0 +1,85 @@
+import type {
+  FastifyReply,
+  FastifyRequest
+} from "fastify";
+import {
+  successResponse
+} from "../../core/http/api-response";
+import {
+  AuthService
+} from "./auth.service";
+import type {
+  LoginInput,
+  RefreshInput,
+  RegisterInput
+} from "./auth.types";
+
+export async function registerController(
+  request: FastifyRequest<{
+    Body: RegisterInput;
+  }>,
+  reply: FastifyReply
+): Promise<FastifyReply> {
+  const service =
+    new AuthService(request.server);
+
+  const result = await service.register(
+    request.body
+  );
+
+  return reply.status(201).send(
+    successResponse(result)
+  );
+}
+
+export async function loginController(
+  request: FastifyRequest<{
+    Body: LoginInput;
+  }>,
+  reply: FastifyReply
+): Promise<FastifyReply> {
+  const service =
+    new AuthService(request.server);
+
+  const result = await service.login(
+    request.body
+  );
+
+  return reply.send(
+    successResponse(result)
+  );
+}
+
+export async function refreshController(
+  request: FastifyRequest<{
+    Body: RefreshInput;
+  }>,
+  reply: FastifyReply
+): Promise<FastifyReply> {
+  const service =
+    new AuthService(request.server);
+
+  const tokens = await service.refresh(
+    request.body.refreshToken
+  );
+
+  return reply.send(
+    successResponse(tokens)
+  );
+}
+
+export async function logoutController(
+  request: FastifyRequest<{
+    Body: RefreshInput;
+  }>,
+  reply: FastifyReply
+): Promise<FastifyReply> {
+  const service =
+    new AuthService(request.server);
+
+  await service.logout(
+    request.body.refreshToken
+  );
+
+  return reply.status(204).send();
+}

dist/templates/api/src/modules/auth/auth.repository.ts

@@ -0,0 +1,77 @@
+import type {
+  PrismaClient,
+  RefreshToken,
+  User
+} from "@prisma/client";
+
+export class AuthRepository {
+  constructor(
+    private readonly prisma: PrismaClient
+  ) {}
+
+  findUserByEmail(email: string): Promise<User | null> {
+    return this.prisma.user.findUnique({
+      where: {
+        email
+      }
+    });
+  }
+
+  createUser(input: {
+    email: string;
+    name: string | null;
+    passwordHash: string;
+  }): Promise<User> {
+    return this.prisma.user.create({
+      data: input
+    });
+  }
+
+  createRefreshToken(input: {
+    tokenHash: string;
+    userId: string;
+    expiresAt: Date;
+  }): Promise<RefreshToken> {
+    return this.prisma.refreshToken.create({
+      data: input
+    });
+  }
+
+  findRefreshTokenWithUser(tokenHash: string) {
+    return this.prisma.refreshToken.findUnique({
+      where: {
+        tokenHash
+      },
+      include: {
+        user: true
+      }
+    });
+  }
+
+  revokeRefreshToken(id: string): Promise<RefreshToken> {
+    return this.prisma.refreshToken.update({
+      where: {
+        id
+      },
+      data: {
+        revokedAt: new Date()
+      }
+    });
+  }
+
+  revokeRefreshTokensByHash(
+    tokenHash: string
+  ): Promise<{
+    count: number;
+  }> {
+    return this.prisma.refreshToken.updateMany({
+      where: {
+        tokenHash,
+        revokedAt: null
+      },
+      data: {
+        revokedAt: new Date()
+      }
+    });
+  }
+}

dist/templates/api/src/modules/auth/auth.routes.ts

@@ -1,52 +1,78 @@
-import type { FastifyPluginAsync } from "fastify";
-import { loginSchema, logoutSchema, meSchema, refreshSchema, registerSchema } from "./auth.schemas";
-import { loginUser, refreshUserTokens, registerUser, revokeRefreshToken } from "./auth.service";
-import type { LoginInput, RefreshInput, RegisterInput } from "./auth.types";
+import type {
+  FastifyPluginAsync
+} from "fastify";
+import {
+  getCurrentUserController
+} from "../users/user.controller";
+import {
+  loginController,
+  logoutController,
+  refreshController,
+  registerController
+} from "./auth.controller";
+import {
+  loginSchema,
+  logoutSchema,
+  meSchema,
+  refreshSchema,
+  registerSchema
+} from "./auth.schemas";
+import type {
+  LoginInput,
+  RefreshInput,
+  RegisterInput
+} from "./auth.types";
 
-export const authRoutes: FastifyPluginAsync = async (app) => {
-  app.post<{ Body: RegisterInput }>(
+export const authRoutes:
+FastifyPluginAsync = async (app) => {
+  app.post<{
+    Body: RegisterInput;
+  }>(
     "/register",
-    { schema: registerSchema },
-    async (request, reply) => {
-      const result = await registerUser(app, request.body);
-      return reply.status(201).send(result);
-    }
+    {
+      schema: registerSchema
+    },
+    registerController
   );
 
-  app.post<{ Body: LoginInput }>(
+  app.post<{
+    Body: LoginInput;
+  }>(
     "/login",
-    { schema: loginSchema },
-    async (request) => loginUser(app, request.body)
+    {
+      schema: loginSchema
+    },
+    loginController
   );
 
-  app.post<{ Body: RefreshInput }>(
+  app.post<{
+    Body: RefreshInput;
+  }>(
     "/refresh",
-    { schema: refreshSchema },
-    async (request) => refreshUserTokens(app, request.body.refreshToken)
+    {
+      schema: refreshSchema
+    },
+    refreshController
   );
 
-  app.post<{ Body: RefreshInput }>(
+  app.post<{
+    Body: RefreshInput;
+  }>(
     "/logout",
-    { schema: logoutSchema },
-    async (request, reply) => {
-      await revokeRefreshToken(app, request.body.refreshToken);
-      return reply.status(204).send();
-    }
+    {
+      schema: logoutSchema
+    },
+    logoutController
   );
 
   app.get(
     "/me",
-    { schema: meSchema, preHandler: [app.authenticate] },
-    async (request) => app.prisma.user.findUniqueOrThrow({
-      where: { id: request.user.sub },
-      select: {
-        id: true,
-        email: true,
-        name: true,
-        role: true,
-        createdAt: true,
-        updatedAt: true
-      }
-    })
+    {
+      schema: meSchema,
+      preHandler: [
+        app.authenticate
+      ]
+    },
+    getCurrentUserController
   );
 };