928ad18d7e
- Improved `accountService` to streamline user profile management, including enhanced fetching and updating mechanisms for profile and address information. - Updated `auth.store` to optimize client-side authentication state handling, ensuring a more robust login, signup, and session management process. - Centralized exports for authentication services in `auth/api/index.ts` for better organization and accessibility. - Enhanced overall service architecture by refining API services related to billing and checkout functionalities, promoting maintainability and clarity across the portal features.
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
|