add docs

2026-07-02 15:59:46 +03:30
parent a8a6f085d0
commit dcd8455106
5 changed files with 811 additions and 0 deletions
@@ -0,0 +1,163 @@
+# Architecture
+
+Negareh API is a NestJS backend built on **Fastify**, **PostgreSQL** (via MikroORM), and **Redis** (caching, OTP, queues). It powers both the customer-facing app and the admin console.
+
+## Tech stack
+
+| Layer | Technology |
+|-------|------------|
+| Runtime | Node.js, TypeScript |
+| Framework | NestJS 11 |
+| HTTP server | Fastify (`@nestjs/platform-fastify`) |
+| ORM | MikroORM 6 (PostgreSQL driver) |
+| Auth | JWT + refresh tokens, OTP via SMS |
+| Cache / OTP | Redis (`@keyv/redis`, `CacheService`) |
+| Jobs | BullMQ (`@nestjs/bullmq`) |
+| Real-time | Socket.IO (notifications) |
+| File storage | AWS S3-compatible bucket |
+| Payments | Zarinpal gateway |
+| API docs | Swagger at `/docs` |
+
+## High-level layout
+
+```
+src/
+├── main.ts                 # Bootstrap: Fastify, pipes, interceptors, CORS, Swagger
+├── app.module.ts           # Root module — wires all feature modules
+├── config/                 # MikroORM, cache, HTTP, Swagger
+├── core/                   # Cross-cutting: exceptions, interceptors, middlewares
+├── common/                 # Shared entities, decorators, enums, interfaces
+├── modules/                # Feature modules (domain boundaries)
+└── seeders/                # Database seed data
+
+database/
+└── migrations/             # Versioned schema changes (MikroORM migrations)
+```
+
+## Feature modules
+
+Each domain lives under `src/modules/<name>/` with a consistent internal structure:
+
+```
+modules/<feature>/
+├── <feature>.module.ts
+├── controllers/            # HTTP layer (thin)
+├── providers/              # Business logic (services)
+├── repositories/           # Data access (extends EntityRepository)
+├── entities/               # MikroORM entities
+├── dto/                    # Request/response validation
+├── listeners/              # Event handlers (@OnEvent)
+├── events/                 # Domain events (EventEmitter2)
+└── enum/                   # Feature-specific enums
+```
+
+Current modules:
+
+- **auth** — OTP login, JWT, refresh tokens
+- **user** — End-user accounts and credit
+- **admin** — Admin accounts
+- **roles** — Roles and permissions (RBAC)
+- **product** — Products and categories
+- **form-builder** — Dynamic product fields and options
+- **request** — Customer requests / quotes
+- **invoice** — Invoicing
+- **order** — Order lifecycle
+- **payment** — Online payments (Zarinpal)
+- **print** — Print-related admin operations
+- **ticket** — Support tickets
+- **chat** — Order/chat messaging
+- **notification** — SMS, push, WebSocket notifications
+- **uploader** — File uploads to S3
+- **announcements**, **learnings**, **criticisms** — Content and feedback
+- **util** — Shared utilities (cache, phone normalization)
+
+## Request lifecycle
+
+1. **Fastify** receives the HTTP request.
+2. **ValidationPipe** validates and transforms DTOs (`class-validator` + `class-transformer`).
+3. **Guards** enforce authentication (`AuthGuard`, `AdminAuthGuard`) and permissions (`@Permissions`).
+4. **Controller** delegates to a **service**.
+5. **Service** uses **repositories** and/or `EntityManager` for persistence.
+6. **ResponseInterceptor** wraps successful responses in a standard envelope.
+7. **HttpExceptionFilter** formats error responses.
+
+## Cross-cutting concerns
+
+### Response envelope
+
+Successful responses:
+
+```json
+{
+  "statusCode": 200,
+  "success": true,
+  "data": { }
+}
+```
+
+Paginated responses also include `meta`:
+
+```json
+{
+  "statusCode": 200,
+  "success": true,
+  "data": [],
+  "meta": { "total": 100, "page": 1, "limit": 10, "totalPages": 10 }
+}
+```
+
+Errors:
+
+```json
+{
+  "statusCode": 400,
+  "success": false,
+  "error": { "message": ["..."] }
+}
+```
+
+### Domain events
+
+Services emit events via `EventEmitter2`. Listeners in `listeners/` handle side effects (notifications, chat, payment follow-up) without bloating the main flow.
+
+### Configuration
+
+Use `ConfigService` for all environment variables. `ConfigModule` is registered globally in `AppModule`. Never read `process.env` directly in application code.
+
+### Rate limiting
+
+`@nestjs/throttler` is configured globally (5 requests per 60 seconds). Sensitive endpoints (OTP, refresh token) use stricter per-route limits via `@Throttle` or custom decorators.
+
+## Design principles
+
+- **Thin controllers, fat services** — HTTP concerns stay in controllers; business rules live in services.
+- **Reuse before rewrite** — Search for existing services, DTOs, and repositories before adding new ones.
+- **Module boundaries** — Features communicate through exported services or domain events, not by reaching into another module's internals.
+- **No duplicated logic** — Extend existing modules rather than copying patterns.
+- **Transactions for multi-entity writes** — Use `em.transactional()` when several rows must commit or roll back together.
+
+## External integrations
+
+| Integration | Purpose |
+|-------------|---------|
+| SMS.ir | OTP and transactional SMS |
+| Zarinpal | Payment gateway |
+| S3-compatible storage | File uploads |
+| Redis | OTP cache, general caching, BullMQ |
+
+## Local development
+
+```bash
+npm install
+npm run start:dev        # Watch mode on APP_PORT (default 4000)
+```
+
+Swagger UI: `http://localhost:4000/docs`
+
+Database helpers (see [database.md](./database.md)):
+
+```bash
+npm run migration:up     # Apply pending migrations
+npm run db:seed          # Run seeders
+npm run db:reset         # Drop, create, migrate, seed (destructive)
+```