ankhbayar/Assist_Design
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Assist_Design/docs/STRUCTURE.md

278 lines
11 KiB
Markdown
Raw Blame History

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/core/` contains app-wide infrastructure:
- `api/`: centralized HTTP client, query keys, response helpers
- `logger/`: application logging utilities
- `providers/`: React context providers (QueryProvider)
- `src/shared/` contains cross-feature utilities:
- `hooks/`: generic React hooks (useLocalStorage, useDebounce, useMediaQuery)
- `utils/`: general utilities (cn, date formatting, error handling)
- `constants/`: data constants (countries, prefectures)
- `src/features/` contains feature modules with consistent structure:
- `api/`: data fetching layer
- `hooks/`: React Query hooks
- `stores/`: Zustand state management
- `components/`: feature-specific UI
- `views/`: page-level views
- Page components in `src/app/` are thin wrappers that import views from features
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**: January 2026
**Status**: ✅ Clean and Organized
Reference in New Issue View Git Blame Copy Permalink