Backend Architecture — Express.js TypeScript API¶

src/app/modules/v1/{Domain}/
├── {domain}.controller.ts     # HTTP request/response handling
├── {domain}.service.ts        # Business logic
├── {domain}.routes.ts         # Express route definitions (some modules use .route.ts — no consistent convention)
├── {domain}.validation.ts     # Zod validation schemas (missing in Image, Public, Purchase; empty in Setting)
└── {domain}.utils.ts          # Domain-specific utilities (optional; some modules use .helpers.ts or .repository.ts)

saas-boilerplate/
├── src/
│   ├── server.ts                    # Entry point — HTTP server + DB init (Vercel handler export)
│   ├── app.ts                       # Express app factory — middleware pipeline
│   ├── config/                      # 8 config files
│   │   ├── index.ts                 # Centralized env config (30+ variable groups)
│   │   ├── AppConfig.ts             # Singleton config class with required env validation at startup
│   │   ├── dbConfig.ts              # TypeORM DataSource configuration (contains nod_env typo)
│   │   ├── passport.ts              # Google OAuth strategy (handles missing email)
│   │   ├── getStripe.ts             # Stripe instance factory
│   │   ├── stripe.ts                # Direct Stripe instance singleton
│   │   ├── cloudinary.ts            # Cloudinary v2 configuration
│   │   └── getLemonsqueezy.ts       # LemonSqueezy SDK setup + checkout
│   ├── db/
│   │   └── connection.ts            # Serverless-safe DataSource singleton
│   ├── entity/                      # 29 TypeORM entities
│   ├── app/
│   │   ├── modules/v1/              # 30 feature modules (see API Modules)
│   │   ├── middlewares/             # 14 middleware files
│   │   │   ├── auth.ts              # JWT authentication guard
│   │   │   ├── hasPermission.ts     # RBAC permission check (legacy — completely unused, zero imports)
│   │   │   ├── permissionMiddleware.ts # Active RBAC: permission() and hasAnyPermission()
│   │   │   ├── contextMiddleware.ts # AsyncLocalStorage request context + permission cache init
│   │   │   ├── globalErrorHandler.ts# Centralized error handler (Zod, Stripe, ApiError)
│   │   │   ├── rateLimiter.ts       # Rate limiting (configurable window/max/message)
│   │   │   ├── requireStripe.ts     # Stripe availability guard
│   │   │   ├── upload.ts            # Multer file upload (memory storage, image types only)
│   │   │   ├── validateRequest.ts   # Zod schema validation (replaces req.body with validated data)
│   │   │   ├── sanitizeQuery.ts     # Query parameter type casting (string→number/boolean)
│   │   │   ├── sequrity.ts          # [sic] Helmet security headers (CSP, HSTS, Frameguard)
│   │   │   ├── swaggerAuthMiddleware.ts # Swagger docs auth (Basic auth + session)
│   │   │   ├── logger.ts            # Winston logging (JSON + PostgreSQL transport)
│   │   │   └── middleware.ts        # Middleware registration + error handler setup
│   │   ├── routes/v1/
│   │   │   ├── index.ts             # Route aggregator (30 route registrations, all under /api/v1/ prefix)
│   │   │   └── webhook.route.ts     # Webhook routes (root-level, before JSON parser)
│   │   ├── events/
│   │   │   ├── eventEmitter.ts      # Node.js EventEmitter singleton
│   │   │   ├── eventTypes.ts        # Event type constants (10 defined, 7 with handlers)
│   │   │   ├── index.ts             # Handler registration
│   │   │   └── handlers/            # 7 event handlers
│   │   ├── cron/
│   │   │   ├── index.ts             # Cron initialization
│   │   │   ├── scheduleResetLoginAttempts.ts
│   │   │   └── subscribtionExpire.ts # [sic] should be subscriptionExpire
│   │   ├── errors/                  # ApiError class + handleZodError utility
│   │   ├── interfaces/              # 8 TypeScript interface files + sanitizer/ subdirectory
│   │   │   └── sanitizer/
│   │   │       └── sanitizer.interface.ts  # ISanitizer interface
│   │   ├── factories/               # Sanitizer factory (DI pattern)
│   │   │   └── sanitizer/
│   │   │       └── sanitizer.factory.ts    # Creates ISanitizer instances
│   │   ├── infrastructure/          # DOMPurify sanitizer implementation
│   │   │   └── sanitizer/
│   │   │       └── dompurify.sanitizer.ts  # DOMPurify backend sanitizer
│   │   ├── transporter/             # PostgresTransport (Winston DB transport)
│   │   ├── policy/                  # Auth validation policies (10 files)
│   │   │   ├── Policy.ts            # Base policy class
│   │   │   └── policies/            # 9 concrete policies
│   │   │       ├── LoginAttemptPolicy.ts   # Login attempt limit validation
│   │   │       ├── LoginPolicy.ts          # Login flow orchestration
│   │   │       ├── OtpPolicy.ts            # OTP verification validation
│   │   │       ├── PasswordAuthPolicy.ts   # Password authentication
│   │   │       ├── RegistrationPolicy.ts   # Registration validation
│   │   │       ├── TokenValidityPolicy.ts  # Password reset token validation
│   │   │       ├── TwoFactorPolicy.ts      # 2FA validation
│   │   │       ├── UserExistencePolicy.ts  # User existence verification
│   │   │       └── UserStatusPolicy.ts     # Account status verification
│   │   └── builder/                 # Query builders (getQueryBuilder.ts + QueryBuilder.ts)
│   ├── lib/                         # Service factories (added alongside legacy shared/ utilities)
│   │   ├── cache/                   # Cache abstraction layer
│   │   │   ├── cache.interface.ts   # ICache interface
│   │   │   └── Node-cache.ts        # NodeCache implementation
│   │   ├── email/                   # Email provider factory — 10 files including template/ subdirectory
│   │   │   ├── EmailFactory.ts      # Provider selection via MAIL_TYPE config
│   │   │   ├── IEmailService.ts     # Email service interface
│   │   │   ├── NodeMailerService.ts  # Nodemailer provider
│   │   │   ├── ResendService.ts     # Resend provider
│   │   │   ├── BrevoService.ts      # Brevo provider
│   │   │   └── ...                  # + type definitions, transporter, template/
│   │   ├── payment/                 # Payment provider factory — 4 files
│   │   │   ├── PaymentFactory.ts    # Provider selection (Stripe only — LemonSqueezy declared but NOT implemented)
│   │   │   ├── StripeService.ts     # Stripe provider
│   │   │   └── ...                  # + type definitions, service
│   │   └── storage/                 # Storage provider factory — 5 files
│   │       ├── StorageFactory.ts    # Provider selection (Cloudinary/S3 only — Local file exists but NOT integrated)
│   │       ├── CloudinaryStorage.ts # Cloudinary provider
│   │       ├── AwsStorage.ts        # AWS S3 provider
│   │       ├── LocalSotrage.ts      # [sic] Local storage (exists but unused by factory)
│   │       └── IStorageService.ts   # Storage interface
│   ├── shared/                      # 15 shared utility files (legacy cache.ts still here despite lib/cache/)
│   │   ├── catchAsync.ts            # Async error wrapper for RequestHandler
│   │   ├── sendResponse.ts          # Standardized JSON response format
│   │   ├── cache.ts                 # Legacy node-cache wrapper (1hr TTL, prefix-based invalidation)
│   │   ├── permissionCache.ts       # Request-scoped permission cache (Set<string>) with ownership validation
│   │   ├── permissionNormalizer.ts  # Bidirectional format conversion: /route/action ↔ resource.action
│   │   ├── requestContext.ts        # AsyncLocalStorage: RequestContext {user, permissionCache, requestId}
│   │   ├── getCorsOrigins.ts        # Parses ALLOWED_ORIGINS env var
│   │   ├── getDataSource.ts         # TypeORM DataSource accessor
│   │   ├── getDbRepository.ts       # Generic repository factory (by entity class or table name)
│   │   ├── getSortQuery.ts          # Dynamic sort builder for queries
│   │   ├── generateUniqueSlug.ts    # Slug generator with uniqueness check
│   │   ├── pick.ts                  # Object property picker utility
│   │   ├── sanitizeImageName.ts     # Image filename sanitizer
│   │   ├── normalizeImageSrc.ts     # Image URL normalizer
│   │   └── validatePostTypeAndId.ts # Menu post type validator
│   ├── helper/                        # 24+ utility files (top-level + cloud/ and email/ subdirectories)
│   │   ├── uploadToCloudinary.ts     # Cloudinary upload (auto-converts to WebP)
│   │   └── httpLogger.ts            # Winston HTTP logger
│   ├── seed/                        # Database seeders (6 files: seed.ts, permission.seed.ts, role.seed.ts, setting.seed.ts + data/permission.ts, data/setting.ts)
│   ├── template/                    # 5 Email HTML templates
│   └── public/                      # Static files (swagger.yaml)
├── solution docs/                   # Applied fix documentation (AUTH, JWT, OTP, HASHED_PASSWORD, CONFIG, PASSPORT)
├── package.json
├── tsconfig.json                    # ES2016 target, CommonJS modules, strict mode
├── .env.example                     # 30+ env variable groups
└── CLAUDE.md                        # AI assistant context file

Request
 ├─ 1. securityMiddleware (sequrity.ts)  # Helmet: CSP, HSTS, Frameguard, noSniff
 ├─ 2. cookieParser()                    # Parse cookies
 ├─ 3. Request logger                    # Console log method + path (dev)
 ├─ 4. compression()                     # Gzip responses
 ├─ 5. cors({ credentials: true })       # Dynamic CORS origins from ALLOWED_ORIGINS
 ├─ 6. express-session                   # Sessions for OAuth (httpOnly, 30-day max)
 ├─ 7. passport.initialize/session       # OAuth middleware
 ├─ 8. express.json() + urlencoded()     # Body parsers
 ├─ 9. Request start time tracker        # For response time metrics
 ├─ 10. contextMiddleware               # AsyncLocalStorage + permission cache init (global for all routes; also listed per-route because it has dual-path behavior: OAuth requests get full context loading, JWT-authenticated requests may short-circuit)

 ├─ 11. /webhooks/* (RAW body)           # Stripe/LemonSqueezy webhooks (before JSON parse)
 ├─ 12. GET / (root welcome)             # Health check / welcome
 ├─ 13. express.static('/uploads')       # Static file serving
 ├─ 14. /api/v1/* → router              # Main API routes (30 modules)
 ├─ 15. globalErrorHandler              # Zod, Stripe, ApiError error handling
 └─ 16. 404 handler                      # Not found JSON response

src/app/interfaces/sanitizer/sanitizer.interface.ts   # ISanitizer interface
src/app/infrastructure/sanitizer/dompurify.sanitizer.ts # DOMPurify implementation
src/app/factories/sanitizer/sanitizer.factory.ts       # Factory creating ISanitizer instances

Auth/
├── auth.controller.ts          # Main controller (typo fixed: was auth.contoroller.ts)
├── auth.service.ts             # Main service with policy-based validation
├── auth.route.ts               # Route definitions (createAccount renamed to requestRegistration)
├── auth.utils.ts               # Auth utilities (setTokenCookie with corrected maxAge)
├── auth.validation.ts          # Zod validation schemas (password min-length updated)
├── google-oauth.controller.ts  # OAuth-specific controller (extra controller outside standard pattern)
└── handlers/                   # Extracted auth handlers
    ├── LoginAttemptHandler.ts   # Login attempt tracking/lockout
    ├── OtpHandler.ts            # OTP generation (crypto.randomInt CSPRNG) and verification
    ├── TokenHandler.ts          # JWT generation and refresh token expiration
    └── UserHandler.ts           # User account operations + OTP password handling (async bcrypt)