247 lines
8.9 KiB
Markdown
247 lines
8.9 KiB
Markdown
|
Repository structure and conventions
|
||
|
|
|
||
|
|
This monorepo hosts the portal (Next.js) and BFF (NestJS), plus shared types.
|
||
|
|
|
||
|
|
High-level layout
|
||
|
|
|
||
|
|
- apps/
|
||
|
|
- portal/ (Next.js)
|
||
|
|
- bff/ (NestJS)
|
||
|
|
- packages/
|
||
|
|
- shared/ (domain types/utilities)
|
||
|
|
- scripts/, docker/, docs/
|
||
|
|
|
||
|
|
Configuration
|
||
|
|
|
||
|
|
- Single root ESLint flat config (eslint.config.mjs) for all packages
|
||
|
|
- Single Prettier config (.prettierrc) and EditorConfig (.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)
|
||
|
|
|
||
|
|
Shared package
|
||
|
|
|
||
|
|
- Domain folders (billing, subscriptions, cases) exporting typed models
|
||
|
|
- No runtime dependencies; 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 # ✅ Comprehensive guide
|
||
|
|
│ ├── GETTING_STARTED.md # ✅ Quick start guide
|
||
|
|
│ ├── RUN.md # ✅ Development workflow
|
||
|
|
│ ├── DEPLOY.md # ✅ Production deployment
|
||
|
|
│ ├── LOGGING.md # ✅ Logging configuration
|
||
|
|
│ └── STRUCTURE.md # ✅ This file
|
||
|
|
│
|
||
|
|
├── 📦 packages/ # Shared packages
|
||
|
|
│ └── shared/ # Shared TypeScript utilities
|
||
|
|
│ ├── package.json # ✅ Shared package config
|
||
|
|
│ ├── tsconfig.json # ✅ Shared TypeScript config
|
||
|
|
│ └── src/ # ✅ Shared source code
|
||
|
|
│
|
||
|
|
└── 🔒 secrets/ # Secure key storage (gitignored)
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🎯 **Environment Configuration**
|
||
|
|
|
||
|
|
### **Environment Template Approach**
|
||
|
|
|
||
|
|
- **`.env.dev.example`** - Development-optimized template
|
||
|
|
- **`.env.production.example`** - Production-optimized template
|
||
|
|
- **`.env.example`** - Basic template for custom setups
|
||
|
|
- **`.env`** - Your actual configuration (gitignored)
|
||
|
|
- **Environment-specific defaults** - Appropriate values per environment
|
||
|
|
|
||
|
|
### **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**
|
||
|
|
|
||
|
|
- **`README.md`** - Project overview and architecture
|
||
|
|
- **`GETTING_STARTED.md`** - Quick setup guide
|
||
|
|
- **`RUN.md`** - Development workflow
|
||
|
|
- **`DEPLOY.md`** - Production deployment
|
||
|
|
- **`LOGGING.md`** - Logging configuration
|
||
|
|
- **`SECURITY.md`** - Security features and best practices
|
||
|
|
- **`STRUCTURE.md`** - This file
|
||
|
|
|
||
|
|
### **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
|