175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
|
# BFF Architecture
|
||
|
|
|
||
|
|
This document outlines the folder structure and architectural boundaries in the BFF (Backend for Frontend).
|
||
|
|
|
||
|
|
## Folder Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
apps/bff/src/
|
||
|
|
├── app/ # Application bootstrap
|
||
|
|
│ └── bootstrap.ts # App initialization and setup
|
||
|
|
├── core/ # Framework configuration (NestJS setup)
|
||
|
|
│ ├── config/ # App configuration and environment validation
|
||
|
|
│ ├── exceptions/ # Global exception filters
|
||
|
|
│ ├── health/ # Health check endpoints
|
||
|
|
│ ├── http/ # HTTP interceptors and middleware
|
||
|
|
│ ├── logging/ # Logger configuration
|
||
|
|
│ ├── rate-limiting/ # Rate limiter setup
|
||
|
|
│ ├── security/ # Security guards, CSRF, etc.
|
||
|
|
│ └── utils/ # Core utilities
|
||
|
|
├── infra/ # External service adapters
|
||
|
|
│ ├── audit/ # Audit logging
|
||
|
|
│ ├── cache/ # Cache service abstractions
|
||
|
|
│ ├── database/ # Prisma database access
|
||
|
|
│ ├── email/ # Email service
|
||
|
|
│ ├── mappers/ # Generic data mappers
|
||
|
|
│ ├── queue/ # Job queue service
|
||
|
|
│ ├── realtime/ # WebSocket/SSE handlers
|
||
|
|
│ ├── redis/ # Redis client configuration
|
||
|
|
│ └── utils/ # Infra utilities
|
||
|
|
├── integrations/ # External API integrations
|
||
|
|
│ ├── freebit/ # Freebit API client
|
||
|
|
│ ├── salesforce/ # Salesforce API client
|
||
|
|
│ ├── sftp/ # SFTP file transfers
|
||
|
|
│ └── whmcs/ # WHMCS API client
|
||
|
|
├── modules/ # Feature modules (business logic)
|
||
|
|
│ ├── auth/ # Authentication module
|
||
|
|
│ ├── billing/ # Billing and invoices
|
||
|
|
│ ├── currency/ # Currency management
|
||
|
|
│ ├── health/ # Health checks
|
||
|
|
│ ├── id-mappings/ # ID mapping service
|
||
|
|
│ ├── me-status/ # User status endpoint
|
||
|
|
│ ├── notifications/ # Notification management
|
||
|
|
│ ├── orders/ # Order management
|
||
|
|
│ ├── realtime/ # Real-time events
|
||
|
|
│ ├── services/ # Service catalog
|
||
|
|
│ ├── subscriptions/ # Subscription management
|
||
|
|
│ ├── support/ # Support tickets
|
||
|
|
│ ├── users/ # User management
|
||
|
|
│ └── verification/ # Identity verification
|
||
|
|
├── types/ # Type declarations
|
||
|
|
├── app.module.ts # Root NestJS module
|
||
|
|
└── main.ts # Application entry point
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architectural Boundaries
|
||
|
|
|
||
|
|
### Core (`src/core/`)
|
||
|
|
|
||
|
|
**Purpose**: NestJS framework configuration and cross-cutting concerns.
|
||
|
|
|
||
|
|
**Contains**:
|
||
|
|
|
||
|
|
- App configuration and environment validation (`config/`)
|
||
|
|
- Global exception filters and error handling (`exceptions/`)
|
||
|
|
- HTTP interceptors, middleware, and guards (`http/`)
|
||
|
|
- Logger setup and configuration (`logging/`)
|
||
|
|
- Rate limiting configuration (`rate-limiting/`)
|
||
|
|
- Security guards, CSRF protection, cookie handling (`security/`)
|
||
|
|
- Core utilities used across the app (`utils/`)
|
||
|
|
|
||
|
|
**Rules**:
|
||
|
|
|
||
|
|
- Core modules should not import from `modules/` or `integrations/`
|
||
|
|
- Core provides the foundation that other layers build upon
|
||
|
|
- Keep framework-specific code here
|
||
|
|
|
||
|
|
### Infra (`src/infra/`)
|
||
|
|
|
||
|
|
**Purpose**: Adapters for external services and infrastructure.
|
||
|
|
|
||
|
|
**Contains**:
|
||
|
|
|
||
|
|
- Database access via Prisma (`database/`)
|
||
|
|
- Cache abstractions for Redis (`cache/`)
|
||
|
|
- Redis client configuration (`redis/`)
|
||
|
|
- Email service (`email/`)
|
||
|
|
- Job queue management (`queue/`)
|
||
|
|
- WebSocket/SSE real-time handlers (`realtime/`)
|
||
|
|
- Audit logging (`audit/`)
|
||
|
|
- Generic data mappers (`mappers/`)
|
||
|
|
|
||
|
|
**Rules**:
|
||
|
|
|
||
|
|
- Infra modules provide abstractions over external dependencies
|
||
|
|
- Should not contain business logic
|
||
|
|
- Can be imported by `modules/` and `integrations/`
|
||
|
|
|
||
|
|
### Integrations (`src/integrations/`)
|
||
|
|
|
||
|
|
**Purpose**: External API clients for third-party services.
|
||
|
|
|
||
|
|
**Contains**:
|
||
|
|
|
||
|
|
- WHMCS API client and transformers
|
||
|
|
- Salesforce API client and event handlers
|
||
|
|
- Freebit API client for SIM management
|
||
|
|
- SFTP client for file transfers
|
||
|
|
|
||
|
|
**Rules**:
|
||
|
|
|
||
|
|
- Each integration is a self-contained NestJS module
|
||
|
|
- Integrations fetch data and transform to domain types
|
||
|
|
- Use domain mappers from `@customer-portal/domain/*/providers`
|
||
|
|
- Should not contain business logic beyond data transformation
|
||
|
|
- Integrations can use `infra/` for caching, logging, etc.
|
||
|
|
|
||
|
|
### Modules (`src/modules/`)
|
||
|
|
|
||
|
|
**Purpose**: Business logic and feature implementation.
|
||
|
|
|
||
|
|
**Contains**:
|
||
|
|
|
||
|
|
- Controllers (thin, validation only)
|
||
|
|
- Services (business logic, orchestration)
|
||
|
|
- Feature-specific utilities
|
||
|
|
|
||
|
|
**Rules**:
|
||
|
|
|
||
|
|
- Controllers validate input and call services
|
||
|
|
- Services orchestrate integrations and apply business rules
|
||
|
|
- Can import from `core/`, `infra/`, and `integrations/`
|
||
|
|
- Should not directly use external APIs (use integrations)
|
||
|
|
|
||
|
|
## Data Flow
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────┐ ┌─────────────┐ ┌───────────────┐ ┌─────────────┐
|
||
|
|
│ Controller │ ──▶ │ Service │ ──▶ │ Integration │ ──▶ │ External API│
|
||
|
|
│ (modules/) │ │ (modules/) │ │(integrations/)│ │ │
|
||
|
|
└─────────────┘ └─────────────┘ └───────────────┘ └─────────────┘
|
||
|
|
│ │ │
|
||
|
|
│ │ │
|
||
|
|
▼ ▼ ▼
|
||
|
|
Validates Orchestrates Transforms
|
||
|
|
input (DTO) business logic to domain types
|
||
|
|
```
|
||
|
|
|
||
|
|
## Import Rules
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
// ✅ Allowed
|
||
|
|
// Modules can import from core, infra, integrations
|
||
|
|
import { ConfigService } from "@/core/config";
|
||
|
|
import { CacheService } from "@/infra/cache";
|
||
|
|
import { WhmcsService } from "@/integrations/whmcs";
|
||
|
|
|
||
|
|
// ✅ Allowed - Domain types and mappers
|
||
|
|
import type { Invoice } from "@customer-portal/domain/billing";
|
||
|
|
import { Whmcs } from "@customer-portal/domain/billing/providers";
|
||
|
|
|
||
|
|
// ❌ Forbidden - Cross-module imports
|
||
|
|
import { BillingService } from "@/modules/billing"; // in another module
|
||
|
|
|
||
|
|
// ❌ Forbidden - Direct external API calls in modules
|
||
|
|
import axios from "axios"; // Use integrations instead
|
||
|
|
```
|
||
|
|
|
||
|
|
## Best Practices
|
||
|
|
|
||
|
|
1. **Controllers are thin**: Only validation, no business logic
|
||
|
|
2. **Services orchestrate**: Combine integrations, apply business rules
|
||
|
|
3. **Integrations transform**: Fetch external data, map to domain types
|
||
|
|
4. **Infra abstracts**: Provide clean interfaces over infrastructure
|
||
|
|
5. **Core configures**: Set up the NestJS framework
|