System Architecture¶

export class TenantContext {
  private static readonly asyncLocalStorage = new AsyncLocalStorage<TenantContextData>();

  static run<T>(context: TenantContextData, callback: () => T): T {
    return this.asyncLocalStorage.run(context, callback);
  }

  static getCurrentTenantId(): string | undefined {
    return this.asyncLocalStorage.getStore()?.tenantId;
  }

  static getCurrentUserId(): string | undefined {
    return this.asyncLocalStorage.getStore()?.userId;
  }
}

@Injectable()
export class SubdomainMiddleware implements NestMiddleware {
  constructor(
    @InjectRepository(Organization)
    private readonly orgRepository: Repository<Organization>,
  ) {}

  async use(req: Request, res: Response, next: NextFunction) {
    const host = req.headers.host || '';
    const subdomain = host.split('.')[0];

    if (subdomain && subdomain !== 'localhost') {
      const org = await this.orgRepository.findOne({
        where: { subdomain },
      });

      if (org) {
        req['organizationId'] = org.id;
      }
    }

    next();
  }
}

@Injectable()
export class TenantContextInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const user = request.user;

    // Get organization ID from user (authenticated) or subdomain (public)
    const organizationId = user?.organizationId || request.organizationId;
    const userId = user?.id;

    // Set tenant context for this request
    return from(
      TenantContext.run(
        {
          tenantId: organizationId?.toString(),
          userId: userId?.toString(),
          roles: user?.getRolesArray() || [],
        },
        () => next.handle().toPromise(),
      ),
    );
  }
}

export class TenantScopedRepository<Entity> extends Repository<Entity> {
  async find(options?: FindManyOptions<Entity>): Promise<Entity[]> {
    const tenantId = TenantContext.getCurrentTenantId();

    if (!tenantId) {
      throw new Error('Tenant context is required for find operation');
    }

    return super.find({
      ...options,
      where: {
        ...options?.where,
        organizationId: parseInt(tenantId, 10),
      },
    });
  }

  // Similar overrides for findOne, findBy, count, etc.

  createTenantQueryBuilder(alias: string): SelectQueryBuilder<Entity> {
    const tenantId = TenantContext.getCurrentTenantId();

    if (!tenantId) {
      throw new Error('Tenant context is required for query builder');
    }

    return this.createQueryBuilder(alias).where(
      `${alias}.organizationId = :organizationId`,
      { organizationId: parseInt(tenantId, 10) },
    );
  }
}

export abstract class BaseEntity {
  @Column({ name: 'tenant_id', type: 'varchar', length: 36, nullable: true })
  tenantId?: string;

  @CreateDateColumn({ name: 'created_at' })
  createdAt: Date;

  @UpdateDateColumn({ name: 'updated_at' })
  updatedAt: Date;

  @Column({ name: 'created_by', nullable: true })
  createdBy?: string;

  @Column({ name: 'updated_by', nullable: true })
  updatedBy?: string;

  @BeforeInsert()
  setTenantId() {
    if (!this.tenantId) {
      this.tenantId = TenantContext.getCurrentTenantId();
    }
  }

  @BeforeUpdate()
  preventCrossTenantModification() {
    const currentTenantId = TenantContext.getCurrentTenantId();
    if (this.tenantId && this.tenantId !== currentTenantId) {
      throw new Error('Cannot modify entity from different tenant');
    }
  }
}

export class ResponseBuilder {
  static success<T>(
    data: T,
    message: string = 'Operation successful',
  ): ApiResponse<T> {
    return { success: true, data, message };
  }

  static error(
    error: string,
    message: string = 'Operation failed',
    statusCode: number = 500,
  ): ApiErrorResponse {
    return { success: false, error, message, statusCode };
  }

  static paginated<T>(
    data: T[],
    page: number,
    limit: number,
    total: number,
    message: string = 'Data retrieved successfully',
  ): PaginatedResponse<T> {
    return {
      success: true,
      data,
      message,
      pagination: {
        page,
        limit,
        total,
        totalPages: Math.ceil(total / limit),
      },
    };
  }
}

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    let status = HttpStatus.INTERNAL_SERVER_ERROR;
    let message = 'Internal server error';

    if (exception instanceof HttpException) {
      status = exception.getStatus();
      const exceptionResponse = exception.getResponse();
      message = typeof exceptionResponse === 'string'
        ? exceptionResponse
        : (exceptionResponse as any).message;
    }

    response.status(status).json(
      ResponseBuilder.error(exception.message, message, status),
    );
  }
}

export const Auth = (...roles: string[]) => {
  return applyDecorators(
    UseGuards(JwtAuthGuard, RolesGuard),
    Roles(...roles),
  );
};

// Usage:
@Auth()              // Any authenticated user
@Auth('admin')       // Admin only
@Auth('admin', 'staff')  // Admin or staff

export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): User => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

// Usage:
async getProfile(@CurrentUser() user: User) {
  return user;
}

// hooks/useProducts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { productsApi } from '@/services/products.service';

export function useProducts(params?: ProductQueryParams) {
  return useQuery({
    queryKey: ['products', params],
    queryFn: () => productsApi.getAll(params),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

export function useCreateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateProductDto) => productsApi.create(data),
    onSuccess: () => {
      // Invalidate and refetch
      queryClient.invalidateQueries({ queryKey: ['products'] });
    },
  });
}

// stores/authStore.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface AuthState {
  user: User | null;
  tokens: Tokens | null;
  setUser: (user: User) => void;
  setTokens: (tokens: Tokens) => void;
  logout: () => void;
}

export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      tokens: null,
      setUser: (user) => set({ user }),
      setTokens: (tokens) => set({ tokens }),
      logout: () => set({ user: null, tokens: null }),
    }),
    { name: 'auth-storage' },
  ),
);

import axios from 'axios';

export const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001/api',
  timeout: 10000,
});

// Request interceptor: Add auth token
apiClient.interceptors.request.use((config) => {
  const tokens = localStorage.getItem('auth-storage');
  if (tokens) {
    const { accessToken } = JSON.parse(tokens).state.tokens;
    config.headers.Authorization = `Bearer ${accessToken}`;
  }
  return config;
});

// Response interceptor: Handle errors and token refresh
apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      // Attempt token refresh
      try {
        const refreshToken = getRefreshToken();
        const { data } = await axios.post('/auth/refresh', { refreshToken });
        setTokens(data.tokens);
        // Retry original request
        return apiClient(error.config);
      } catch (refreshError) {
        // Redirect to login
        window.location.href = '/login';
      }
    }
    return Promise.reject(error);
  },
);

// packages/types/src/auth/index.ts
export interface User {
  id: number;
  email: string;
  firstName: string;
  lastName: string;
  organizationId: number;
  roles: string[];
}

export interface AuthResponse {
  user: User;
  organization: Organization;
  tokens: Tokens;
}

// packages/schemas/src/auth/login.schema.ts
import { z } from 'zod';

export const loginSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

export type LoginDto = z.infer<typeof loginSchema>;

// On login:
// Key: org:{orgId}:session:{userId}
// Value: { userId, email, organizationId, roles, organization, lastActivity }
// TTL: 3600 seconds (1 hour, sliding window)

await cacheService.set(
  organizationId,
  `session:${userId}`,
  {
    userId,
    email,
    organizationId,
    roles: user.getRolesArray(),
    organization,
    lastActivity: Date.now(),
  },
  3600,  // 1 hour TTL
);

// On GET /api/auth/me:
const cachedSession = await cacheService.get(orgId, `session:${userId}`);
if (cachedSession) {
  return cachedSession;  // Ultra-fast response <10ms
}

// On logout:
// Key: system:auth:blacklist:{jti}
// Value: true
// TTL: 900 seconds (15 min = access token expiry)

await cacheService.setSystem(`auth:blacklist:${jti}`, true, 900);

// JWT Strategy checks blacklist:
const isBlacklisted = await cacheService.getSystem(`auth:blacklist:${jti}`);
if (isBlacklisted) {
  throw new UnauthorizedException('Token has been revoked');
}

// On /api/auth/refresh:
// 1. Validate old refresh token
// 2. Delete old refresh token from Redis
// 3. Generate NEW access token + NEW refresh token
// 4. Store new refresh token in Redis
// 5. Return both tokens

// Key: system:auth:refresh:{userId}:{jti}
// Value: true
// TTL: 604800 seconds (7 days)

// User entity method
getRolesArray(): string[] {
  if (!this.roles) return [];

  const roleMap = {
    '[a]': 'admin',
    '[s]': 'staff',
    '[c]': 'client',
    '[su]': 'superuser',
    '[co]': 'coordinator',
  };

  return Object.entries(roleMap)
    .filter(([key]) => this.roles.includes(key))
    .map(([, value]) => value);
}

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!requiredRoles) return true;

    const request = context.switchToHttp().getRequest();
    const user = request.user;

    // OR logic: User must have at least one required role
    return requiredRoles.some(role => user.getRolesArray().includes(role));
  }
}

// main.ts
import * as csurf from 'csurf';

app.use(csurf({
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'strict',
  },
}));

// Get CSRF token endpoint
@Get('auth/csrf-token')
getCsrfToken(@Req() req: Request) {
  return { csrfToken: req.csrfToken() };
}

// Global rate limiting
@Module({
  imports: [
    ThrottlerModule.forRoot({
      ttl: 60,     // 60 seconds
      limit: 100,  // 100 requests per minute
    }),
  ],
})

// Login-specific rate limiting
async checkRateLimit(email: string): Promise<void> {
  const key = `auth:failed:${email}`;
  const attempts = await this.cacheService.getSystem(key);

  if (attempts && attempts.count >= 5) {
    const blockedUntil = new Date(attempts.blockedUntil);
    if (blockedUntil > new Date()) {
      throw new BadRequestException('Too many failed attempts. Try again later.');
    }
  }
}

// DTO with class-validator
import { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';

export class CreateProductDto {
  @IsString()
  @MinLength(3)
  @MaxLength(255)
  @ApiProperty({ example: 'iPhone 15 Pro' })
  name: string;

  @IsNumber()
  @Min(0)
  @ApiProperty({ example: 999.99 })
  price: number;

  @IsString()
  @Length(5, 50)
  @ApiProperty({ example: 'PROD-001' })
  sku: string;
}

import * as bcrypt from 'bcrypt';

// Hash password (12 rounds)
const passwordHash = await bcrypt.hash(password, 12);

// Verify password
const isValid = await bcrypt.compare(password, user.passwordHash);

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
      imgSrc: ["'self'", 'data:', 'https:'],
    },
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true,
  },
}));

// Success
{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

// Paginated
{
  "success": true,
  "data": [ ... ],
  "message": "Products retrieved successfully",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

// Error
{
  "success": false,
  "error": "NotFoundException",
  "message": "Product not found",
  "statusCode": 404
}

// Query DTO
export class PaginationQueryDto {
  @IsOptional()
  @IsInt()
  @Min(1)
  @Type(() => Number)
  page?: number = 1;

  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(100)
  @Type(() => Number)
  limit?: number = 10;
}

// Service implementation
async findAll(query: PaginationQueryDto) {
  const [data, total] = await this.repository.findAndCount({
    skip: (query.page - 1) * query.limit,
    take: query.limit,
  });

  return ResponseBuilder.paginated(data, query.page, query.limit, total);
}

// Service throws exceptions
throw new NotFoundException(`Product with ID ${id} not found`);
throw new BadRequestException('Invalid product data');
throw new UnauthorizedException('Invalid credentials');

// AllExceptionsFilter catches and formats
{
  "success": false,
  "error": "NotFoundException",
  "message": "Product with ID 999 not found",
  "statusCode": 404
}

// On user update
await this.cacheService.del(organizationId, `session:${userId}`);

// On logout
await this.cacheService.del(organizationId, `session:${userId}`);
await this.cacheService.delSystem(`auth:refresh:${userId}:${jti}`);
await this.cacheService.setSystem(`auth:blacklist:${jti}`, true, 900);

// config/database.config.ts
export const databaseConfig = {
  type: 'mysql',
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT, 10),
  database: process.env.DB_NAME,
  extra: {
    connectionLimit: 10,  // Max connections per instance
  },
};

// Redis Cluster config
const redis = new Redis.Cluster([
  { host: 'redis-node-1', port: 6379 },
  { host: 'redis-node-2', port: 6379 },
  { host: 'redis-node-3', port: 6379 },
]);