10c8461661
- Introduced Zod DTOs for request validation across multiple controllers, replacing inline validation with structured classes for improved maintainability and clarity. - Updated ESLint configuration to enforce a rule against importing Zod directly in BFF controllers, promoting the use of shared domain schemas for request validation. - Removed the SecureErrorMapperService to streamline the security module, as its functionality was deemed unnecessary. - Enhanced various controllers to utilize the new DTOs, ensuring consistent validation and response handling across the application.
271 lines
11 KiB
Markdown
271 lines
11 KiB
Markdown
Repository structure and conventions
|
|
|
|
This monorepo hosts the portal (Next.js) and BFF (NestJS), plus domain types.
|
|
|
|
High-level layout
|
|
|
|
- apps/
|
|
- portal/ (Next.js)
|
|
- bff/ (NestJS)
|
|
- packages/
|
|
- domain/ (domain types/utilities)
|
|
- scripts/, docker/, docs/
|
|
|
|
Configuration
|
|
|
|
- Single root ESLint flat config (eslint.config.mjs) for all packages
|
|
- Single Prettier config (config/prettier.config.js) and EditorConfig (config/.editorconfig)
|
|
- Root TypeScript config tsconfig.json extended by packages
|
|
|
|
Portal (Next.js)
|
|
|
|
- src/lib/ contains cross-feature utilities:
|
|
- api.ts: centralized HTTP client (typed, safe JSON parsing)
|
|
- env.ts: zod-validated runtime environment
|
|
- auth/: Zustand store and helpers
|
|
- Hooks live under src/hooks/ and should consume the centralized client
|
|
- Feature barrels are available under src/features/{billing,subscriptions,dashboard}/hooks for stable imports
|
|
- Page components keep UI and delegate data-fetching to hooks
|
|
|
|
BFF (NestJS)
|
|
|
|
- Modules per domain (e.g., invoices, subscriptions)
|
|
- Common concerns under src/common/ (logging, filters, config)
|
|
- Strict DTO validation, error filtering (no sensitive data leaks)
|
|
- Auth module layout:
|
|
- `modules/auth/presentation` → controllers, guards, interceptors, passport strategies
|
|
- `modules/auth/application` → orchestration facade coordinating workflows and tokens
|
|
- `modules/auth/infra` → token services, Redis rate limiting, signup/password/WHMCS workflows
|
|
- Zod schemas live in `@customer-portal/domain`; controllers use `ZodValidationPipe`
|
|
|
|
## Validation Workflow (Zod-First)
|
|
|
|
- Shared schemas live in `packages/domain/<domain>/schema.ts` (and helpers in `packages/domain/toolkit/validation/`).
|
|
- BFF registers `nestjs-zod`'s `ZodValidationPipe` globally via `APP_PIPE` (see `apps/bff/src/app.module.ts`).
|
|
- Controllers define DTOs via `createZodDto(schema)` and rely on the global pipe for `@Body()`, `@Param()`, and `@Query()` validation (avoid per-route pipes unless you need an override).
|
|
- Services call `schema.parse` when mapping external data (Salesforce, WHMCS) to ensure the response matches the contract.
|
|
- Frontend imports the same schemas/types (and `useZodForm` helpers) to keep UI validation in sync with backend rules.
|
|
- Error handling runs through custom filters; if custom formatting is needed for Zod errors, catch `ZodValidationException`.
|
|
|
|
Domain package
|
|
|
|
- Domain folders (billing, subscriptions, cases) exporting typed models
|
|
- No framework-specific imports; purely types/utilities
|
|
|
|
Tooling
|
|
|
|
- Pre-commit: format check, lint, type-check via Husky + lint-staged
|
|
- CI: lint, type-check, test, build per app (to be wired)
|
|
|
|
Coding standards
|
|
|
|
- Strict TypeScript rules enforced repository-wide
|
|
- No any in public APIs; avoid unsafe operations
|
|
- Async handlers in React wrapped with void or promise-chaining
|
|
|
|
# 🏗️ Project Structure
|
|
|
|
## 📁 **Current Directory Structure**
|
|
|
|
```
|
|
📦 Customer Portal
|
|
├── 📄 .env.example # ✅ Single environment template
|
|
├── 📄 .env # ✅ Your actual config (gitignored)
|
|
├── 📄 .gitignore # ✅ Comprehensive gitignore
|
|
├── 📄 package.json # ✅ Root package with clean scripts
|
|
├── 📄 pnpm-workspace.yaml # ✅ PNPM workspace config
|
|
├── 📄 tsconfig.json # ✅ TypeScript root config
|
|
├── 📄 README.md # ✅ Project overview
|
|
├── 📄 SECURITY.md # ✅ Security documentation
|
|
│
|
|
├── 🚀 apps/ # Applications
|
|
│ ├── bff/ # NestJS Backend
|
|
│ │ ├── Dockerfile # ✅ Optimized production build
|
|
│ │ ├── package.json # ✅ BFF dependencies
|
|
│ │ ├── tsconfig.json # ✅ BFF TypeScript config
|
|
│ │ ├── nest-cli.json # ✅ NestJS CLI config
|
|
│ │ ├── prisma/ # ✅ Database schema & migrations
|
|
│ │ ├── src/ # ✅ NestJS source code
|
|
│ │ └── test/ # ✅ BFF tests
|
|
│ │
|
|
│ └── portal/ # Next.js Frontend
|
|
│ ├── Dockerfile # ✅ Optimized production build
|
|
│ ├── package.json # ✅ Portal dependencies
|
|
│ ├── tsconfig.json # ✅ Portal TypeScript config
|
|
│ ├── next.config.mjs # ✅ Next.js configuration
|
|
│ ├── components.json # ✅ UI components config
|
|
│ ├── eslint.config.mjs # ✅ ESLint configuration
|
|
│ ├── postcss.config.mjs # ✅ PostCSS configuration
|
|
│ ├── src/ # ✅ Next.js source code
|
|
│ └── public/ # ✅ Static assets
|
|
│
|
|
├── 🐳 docker/ # Docker configurations
|
|
│ ├── dev/ # Development setup
|
|
│ │ └── docker-compose.yml # ✅ Services only (PostgreSQL + Redis)
|
|
│ └── prod/ # Production setup
|
|
│ ├── docker-compose.yml # ✅ Complete production stack
|
|
│ ├── nginx.conf # ✅ Reverse proxy configuration
|
|
│ ├── postgres.conf # ✅ PostgreSQL optimization
|
|
│ └── redis.conf # ✅ Redis optimization
|
|
│
|
|
├── 🛠️ scripts/ # Management scripts
|
|
│ ├── dev/manage.sh # ✅ Development environment manager
|
|
│ ├── prod/manage.sh # ✅ Production deployment manager
|
|
│ └── plesk-deploy.sh # ✅ Plesk deployment script
|
|
│
|
|
├── 📚 docs/ # Documentation
|
|
│ ├── README.md # ✅ Documentation index
|
|
│ ├── STRUCTURE.md # ✅ This file
|
|
│ ├── getting-started/ # Setup and running guides
|
|
│ │ ├── setup.md # Initial project setup
|
|
│ │ ├── running.md # Local development
|
|
│ │ └── deployment.md # Production deployment
|
|
│ ├── architecture/ # System design documents
|
|
│ ├── how-it-works/ # Feature guides
|
|
│ ├── integrations/ # External system integration
|
|
│ ├── development/ # Development guides
|
|
│ ├── operations/ # Operational runbooks
|
|
│ └── _archive/ # Historical documents
|
|
│
|
|
├── 📦 packages/ # Shared packages
|
|
│ └── domain/ # Domain TypeScript utilities
|
|
│ ├── package.json # ✅ Domain package config
|
|
│ ├── tsconfig.json # ✅ Domain TypeScript config
|
|
│ └── src/ # ✅ Domain source code
|
|
│
|
|
└── 🔒 secrets/ # Secure key storage (gitignored)
|
|
```
|
|
|
|
## 🎯 **Environment Configuration**
|
|
|
|
### **Environment Template Approach**
|
|
|
|
Environment templates are located in the `env/` folder:
|
|
|
|
- **`env/dev.env.sample`** - Development environment template
|
|
- **`env/portal-backend.env.sample`** - Backend-specific variables
|
|
- **`env/portal-frontend.env.sample`** - Frontend-specific variables
|
|
- **`.env`** - Your actual configuration (gitignored, at project root)
|
|
|
|
### **Environment Variables**
|
|
|
|
```bash
|
|
# Application
|
|
NODE_ENV=development
|
|
APP_NAME=customer-portal-bff
|
|
BFF_PORT=4000
|
|
|
|
# Security
|
|
JWT_SECRET=your_secure_secret_minimum_32_chars
|
|
BCRYPT_ROUNDS=12
|
|
|
|
# Database & Cache
|
|
DATABASE_URL=postgresql://user:pass@localhost:5432/db
|
|
REDIS_URL=redis://localhost:6379
|
|
|
|
# External APIs
|
|
WHMCS_BASE_URL=https://your-domain.com
|
|
SF_LOGIN_URL=https://login.salesforce.com
|
|
|
|
# Frontend (NEXT_PUBLIC_ variables)
|
|
NEXT_PUBLIC_API_BASE=http://localhost:4000
|
|
```
|
|
|
|
## 🐳 **Docker Organization**
|
|
|
|
### **Development (`docker/dev/`)**
|
|
|
|
- **Services only** - PostgreSQL + Redis
|
|
- **Apps run locally** via `pnpm dev`
|
|
- **Optional tools** - Adminer, Redis Commander
|
|
- **Port exposure** for local development
|
|
|
|
### **Production (`docker/prod/`)**
|
|
|
|
- **Complete stack** - All services containerized
|
|
- **Nginx reverse proxy** with SSL
|
|
- **Optimized configs** for performance
|
|
- **Health checks** and monitoring
|
|
- **No port exposure** (internal networking)
|
|
|
|
## 🛠️ **Scripts Organization**
|
|
|
|
### **Development Scripts (`scripts/dev/`)**
|
|
|
|
```bash
|
|
pnpm dev:start # Start PostgreSQL + Redis
|
|
pnpm dev:stop # Stop services
|
|
pnpm dev:tools # Start with admin tools
|
|
pnpm dev:apps # Start services + local apps
|
|
```
|
|
|
|
### **Production Scripts (`scripts/prod/`)**
|
|
|
|
```bash
|
|
pnpm prod:deploy # Full production deployment
|
|
pnpm prod:start # Start production stack
|
|
pnpm prod:update # Zero-downtime update
|
|
pnpm prod:backup # Database backup
|
|
```
|
|
|
|
## 📚 **Documentation Structure**
|
|
|
|
### **Essential Guides**
|
|
|
|
Documentation is organized in subdirectories:
|
|
|
|
- **`docs/README.md`** - Documentation index and navigation
|
|
- **`docs/STRUCTURE.md`** - This file (project structure)
|
|
- **`docs/getting-started/`** - Setup, running, and deployment guides
|
|
- **`docs/architecture/`** - System design and architecture
|
|
- **`docs/how-it-works/`** - Feature guides and workflows
|
|
- **`docs/integrations/`** - Salesforce, WHMCS, SIM integration
|
|
- **`docs/development/`** - BFF, Portal, Auth development guides
|
|
- **`docs/operations/`** - Runbooks and operational procedures
|
|
|
|
### **No Redundancy**
|
|
|
|
- **Single source of truth** for each topic
|
|
- **Clear separation** of concerns
|
|
- **Consistent formatting** and structure
|
|
|
|
## 🎯 **Key Principles**
|
|
|
|
### **1. Separation of Concerns**
|
|
|
|
- **Dev vs Prod** - Clear separation with appropriate tooling
|
|
- **Services vs Apps** - Development runs apps locally, production containerizes everything
|
|
- **Configuration vs Code** - Environment variables for configuration, code for logic
|
|
|
|
### **2. Single Source of Truth**
|
|
|
|
- **One environment template** - `.env.example`
|
|
- **One Docker Compose** per environment
|
|
- **One script** per operation type
|
|
|
|
### **3. Simplicity**
|
|
|
|
- **Clear naming** - No ambiguous file names
|
|
- **Logical grouping** - Related files in same directory
|
|
- **Minimal nesting** - Flat structure where possible
|
|
|
|
### **4. Production Ready**
|
|
|
|
- **Security first** - All security measures implemented
|
|
- **Performance optimized** - Database and cache tuning
|
|
- **Monitoring ready** - Health checks and logging
|
|
- **Scalable** - Containerized architecture
|
|
|
|
## 🚀 **Getting Started**
|
|
|
|
1. **Copy environment template**: `cp .env.example .env`
|
|
2. **Edit configuration**: Fill in your actual values
|
|
3. **Start development**: `pnpm dev:start` (services) + `pnpm dev` (apps)
|
|
4. **Deploy production**: `pnpm prod:deploy`
|
|
|
|
---
|
|
|
|
**Last Updated**: $(date)
|
|
**Status**: ✅ Clean and Organized
|
|
**Redundancy**: ❌ None Found
|