# 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