03 — Module Architecture (Admin Service)

This document describes the module-level architecture for the Admin Service feature, covering both the auth-api app (admin authentication) and the new admin-api app (admin CRUD operations). It includes C4 component diagrams, module import graphs, provider tables, monorepo import mappings, and a scaffolding file checklist.

1. C4 Component Diagrams

1.1 auth-api App

graph TD
    subgraph "auth-api Application"
        AppModule["AppModule"]
        CustomerAuthMod["CustomerAuthModule"]
        EmployeeAuthMod["EmployeeAuthModule"]
        UserAuthMod["UserAuthModule"]
        AdminAuthMod["AdminAuthModule"]
        TokenMod["TokenModule"]
        SessionMod["SessionModule"]
    end

    subgraph "Shared / Utils"
        SharedMod["SharedModule"]
        PrismaClient["PrismaClientModule"]
        RedisClient["RedisClientModule"]
        EmailSender["EmailSenderModule"]
    end

    subgraph "Config"
        JwtCustomerConfig["JwtCustomerConfigModule"]
        JwtEmployeeConfig["JwtEmployeeConfigModule"]
        JwtAdminConfig["JwtAdminConfigModule"]
        AppConfig["AppConfigModule"]
    end

    subgraph "User API Domain"
        UserCoreMod["UserCoreModule"]
        CustomerCoreMod["CustomerCoreModule"]
    end

    AppModule --> AppConfig
    AppModule --> CustomerAuthMod
    AppModule --> EmployeeAuthMod
    AppModule --> UserAuthMod
    AppModule --> AdminAuthMod

    CustomerAuthMod --> JwtCustomerConfig
    CustomerAuthMod --> UserCoreMod
    CustomerAuthMod --> CustomerCoreMod
    CustomerAuthMod --> TokenMod
    CustomerAuthMod --> SessionMod
    CustomerAuthMod --> RedisClient
    CustomerAuthMod --> EmailSender

    EmployeeAuthMod --> JwtEmployeeConfig
    EmployeeAuthMod --> TokenMod
    EmployeeAuthMod --> SessionMod

    AdminAuthMod --> JwtAdminConfig
    AdminAuthMod --> UserCoreMod
    AdminAuthMod --> TokenMod
    AdminAuthMod --> SessionMod
    AdminAuthMod --> RedisClient
    AdminAuthMod --> EmailSender
    AdminAuthMod --> SharedMod

    TokenMod --> JwtCustomerConfig
    TokenMod --> JwtEmployeeConfig
    TokenMod --> JwtAdminConfig
    TokenMod --> PrismaClient

1.2 admin-api App (New)

graph TD
    subgraph "admin-api Application"
        AdminAppModule["AppModule"]
        AdminProjectMod["AdminProjectModule"]
        AdminUserMod["AdminUserModule"]
    end

    subgraph "Shared / Utils"
        SharedMod["SharedModule"]
        PrismaClient["PrismaClientModule"]
    end

    subgraph "Config"
        JwtAdminConfig["JwtAdminConfigModule"]
        AppConfig["AppConfigModule"]
    end

    subgraph "Data Access"
        AdminDataAccess["AdminApiDataAccess"]
    end

    AdminAppModule --> AppConfig
    AdminAppModule --> AdminProjectMod
    AdminAppModule --> AdminUserMod

    AdminProjectMod --> PrismaClient
    AdminProjectMod --> SharedMod
    AdminProjectMod --> AdminDataAccess

    AdminUserMod --> PrismaClient
    AdminUserMod --> SharedMod
    AdminUserMod --> AdminDataAccess

2. Module Import Graph

This directed graph shows all new and extended module dependencies. No cycles exist.

graph TD
    subgraph "Config Libraries"
        JwtAdminConfig["JwtAdminConfigModule"]
    end

    subgraph "auth-api Feature Libraries"
        AdminAuth["AdminAuthModule"]
        Token["TokenModule (extended)"]
        Session["SessionModule"]
    end

    subgraph "admin-api Feature Libraries"
        AdminProject["AdminProjectModule"]
        AdminUser["AdminUserModule"]
        AdminDataAccess["AdminApiDataAccess"]
    end

    subgraph "Cross-Domain Libraries"
        UserCore["UserCoreModule"]
    end

    subgraph "Shared / Utils"
        Shared["SharedModule"]
        Prisma["PrismaClientModule"]
        Redis["RedisClientModule"]
        EmailSender["EmailSenderModule"]
    end

    %% AdminAuthModule imports
    AdminAuth --> JwtAdminConfig
    AdminAuth --> Token
    AdminAuth --> Session
    AdminAuth --> UserCore
    AdminAuth --> Redis
    AdminAuth --> EmailSender
    AdminAuth --> Shared

    %% TokenModule extended imports
    Token --> JwtAdminConfig

    %% AdminProjectModule imports
    AdminProject --> Prisma
    AdminProject --> Shared
    AdminProject --> AdminDataAccess

    %% AdminUserModule imports
    AdminUser --> Prisma
    AdminUser --> Shared
    AdminUser --> AdminDataAccess

3. Provider Tables

3.1 JwtAdminConfigModule

Column	Value
Module	`JwtAdminConfigModule`
Imports	`ConfigModule.forRoot({ load: [jwtAdminConfig], validationSchema: jwtAdminValidationSchema })`
Providers	`ConfigService`, `JwtAdminConfigService`
Exports	`ConfigService`, `JwtAdminConfigService`
Controllers	None

JwtAdminConfigService exposes: accessSecretKey, accessExpiresIn, refreshSecretKey, refreshExpiresIn.

3.2 AdminAuthModule

Column	Value
Module	`AdminAuthModule`
Imports	`JwtAdminConfigModule`, `UserCoreModule`, `TokenModule`, `SessionModule`, `RedisClientModule`, `EmailSenderModule`
Providers	`AdminAuthService`, `AdminAuthRefreshTokenService`, `AdminAuthVerificationService`, `AdminAccessTokenStrategy`, `AdminRefreshTokenStrategy`, `MapperService`
Exports	None
Controllers	`AdminAuthController`, `AdminAuthRefreshTokenController`, `AdminAuthVerificationController`

3.3 AdminProjectModule

Column	Value
Module	`AdminProjectModule`
Imports	`PrismaClientModule`, `JwtModule.register({})`, `JwtAdminConfigModule`
Providers	`AdminProjectService`, `AdminProjectRepository`, `MapperService`, `AdminGuard`
Exports	`AdminProjectService`
Controllers	`AdminProjectController`

3.4 AdminUserModule

Column	Value
Module	`AdminUserModule`
Imports	`PrismaClientModule`, `JwtModule.register({})`, `JwtAdminConfigModule`
Providers	`AdminUserService`, `AdminUserRepository`, `MapperService`, `AdminGuard`
Exports	`AdminUserService`
Controllers	`AdminUserController`

3.5 TokenModule (Extended)

The existing TokenModule gains one new provider and one new import:

Change	Value
New Import	`JwtAdminConfigModule`
New Provider	`TokenAdminService`
New Export	`TokenAdminService`

After extension, the full module state:

Column	Value
Module	`TokenModule`
Imports	`ScheduleModule.forRoot({})`, `JwtCustomerConfigModule`, `JwtEmployeeConfigModule`, `JwtAdminConfigModule`, `PrismaClientModule`
Providers	`JwtService`, `TokenService`, `TokenCustomerService`, `TokenEmployeeService`, `TokenAdminService`, `TokenJobService`, `TokenRepository`
Exports	`TokenService`, `TokenCustomerService`, `TokenEmployeeService`, `TokenAdminService`
Controllers	None

4. Monorepo Lib Imports Table

Each new module and which @crewsforge-back/* workspace imports it consumes at runtime.

Module	`@crewsforge-back/*` Imports Used
`JwtAdminConfigModule`	None (standalone config; uses `@nestjs/config` only)
`AdminAuthModule`	`@crewsforge-back/apis/configs/auth-api/jwt-admin`, `@crewsforge-back/apis/providers/user-api/features/user`, `@crewsforge-back/apis/providers/auth-api/features/token`, `@crewsforge-back/apis/providers/auth-api/features/session`, `@crewsforge-back/redis-client`, `@crewsforge-back/email-sender-api-features-sender`, `@crewsforge-back/apis/shared`
`AdminProjectModule`	`@crewsforge-back/apis/utils/prisma-client`, `@crewsforge-back/apis/shared`, `@crewsforge-back/apis/providers/admin-api/data-access`, `@crewsforge-back/apis/configs/auth-api/jwt-admin`
`AdminUserModule`	`@crewsforge-back/apis/utils/prisma-client`, `@crewsforge-back/apis/shared`, `@crewsforge-back/apis/providers/admin-api/data-access`, `@crewsforge-back/apis/configs/auth-api/jwt-admin`
`AdminApiDataAccess`	`@crewsforge-back/apis/shared` (DTO base classes / validators only)
`TokenAdminService` (in TokenModule)	`@crewsforge-back/apis/configs/auth-api/jwt-admin`

5. Scaffolding File Checklist

Complete list of files to create per module. Paths are relative to the workspace root. NX boilerplate files (project.json, tsconfig.json, tsconfig.lib.json, tsconfig.spec.json, eslint.config.mjs, jest.config.ts) are generated by the nx g commands documented in 08_nx_structure.md and are omitted here.

5.1 JwtAdminConfigModule

libs/apis/configs/auth-api/jwt-admin/src/
  index.ts
  lib/
    jwt-admin-config.module.ts          # Module definition: imports ConfigModule.forRoot
    jwt-admin-config.service.ts         # Injectable service exposing access/refresh secret + expiry
    jwt-admin.config.ts                 # registerAs config factory reading from process.env
    jwt-admin.env.ts                    # Env variable key constants
    jwt-admin.validation.ts             # Joi validation schema for env vars

5.2 AdminAuthModule

libs/apis/providers/auth-api/features/admin-auth/src/
  index.ts
  lib/
    admin-auth.module.ts                # Module definition
    admin-auth.controller.ts            # POST /sign-in (initiate email verification)
    admin-auth-refresh-token.controller.ts  # POST /refresh (rotate token pair)
    admin-auth-verification.controller.ts   # POST /verify (verify code, create session)
    admin-auth.service.ts               # Core sign-in logic: validate email domain, send code
    admin-auth-refresh-token.service.ts # Token refresh logic
    admin-auth-verification.service.ts  # Code verification, user+role upsert, session creation
    strategies/
      admin-access-token.strategy.ts    # PassportStrategy(Strategy, 'jwt-admin-access')
      admin-refresh-token.strategy.ts   # PassportStrategy(Strategy, 'jwt-admin-refresh')
    constants/
      admin-auth.constants.ts           # Strategy names, Redis key prefixes, code TTL

5.3 AdminProjectModule

libs/apis/providers/admin-api/features/admin-project/src/
  index.ts
  lib/
    admin-project.module.ts             # Module definition
    admin-project.controller.ts         # GET /projects, GET /projects/:id, PATCH /projects/:id/status, DELETE /projects/:id
    admin-project.service.ts            # Business logic: list, get, update status, soft-delete
    admin-project.repository.ts         # Prisma queries with soft-delete filters and pagination

5.4 AdminUserModule

libs/apis/providers/admin-api/features/admin-user/src/
  index.ts
  lib/
    admin-user.module.ts                # Module definition
    admin-user.controller.ts            # GET /users, GET /users/:id, PATCH /users/:id/block
    admin-user.service.ts               # Business logic: list, get, block/unblock
    admin-user.repository.ts            # Prisma queries with pagination and role filtering

5.5 AdminApiDataAccess (DTOs + Constants)

libs/apis/providers/admin-api/data-access/src/
  index.ts
  lib/
    dto/
      block-user.dto.ts                 # { isBlocked: boolean }
      admin-project-query.dto.ts        # Pagination + status filter for project listing
      admin-user-query.dto.ts           # Pagination + role/block filter for user listing
      update-project-status.dto.ts      # { status: ProjectStatus }
    constants/
      admin-api.constants.ts            # Default page size, max page size, route prefixes

5.6 Files Added to Existing Libraries

These files are created inside existing library directories (not new libraries):

Library	New File	Purpose
`libs/apis/providers/auth-api/features/token/`	`src/lib/token-admin.service.ts`	`TokenAdminService` — generates admin JWT pairs using `JwtAdminConfigService`
`libs/apis/shared/`	`src/lib/guards/admin-access-token.guard.ts`	`AdminAccessTokenGuard` — AuthGuard for admin access token strategy
`libs/apis/shared/`	`src/lib/guards/admin-refresh-token.guard.ts`	`AdminRefreshTokenGuard` — AuthGuard for admin refresh token strategy
`libs/apis/shared/`	`src/lib/types/admin.types.ts`	Admin-specific type definitions
`libs/apis/providers/email-sender-api/features/sender/`	`src/lib/templates/admin-verification-code.template.ts`	Email template for admin verification codes

5.7 admin-api App Scaffolding

The new admin-api NestJS application at apps/admin-api/:

apps/admin-api/
  project.json
  tsconfig.json
  tsconfig.app.json
  src/
    main.ts                             # NestFactory bootstrap (same pattern as auth-api/project-api)
    app/
      app.module.ts                     # Imports AppConfigModule, ClsModule, AdminProjectModule, AdminUserModule

main.ts
app/app.module.ts

Summary

Category	Count	Details
New NX lib modules	5	JwtAdminConfigModule, AdminAuthModule, AdminProjectModule, AdminUserModule, AdminApiDataAccess
New NX app	1	`admin-api`
Extended modules	3	TokenModule, SharedModule, EmailSenderModule
Total new source files	~30	Controllers, services, repositories, strategies, DTOs, constants, configs, guards
New app entry points	1	`apps/admin-api/src/main.ts`