NexaFX is a Web3-powered currency exchange platform that supports real-time fiat and crypto conversions. The backend is built using NestJS and interfaces with smart contracts written in Rust on the Stellar network.

flowchart TD
    subgraph Client
        Web[Web App]
        Mobile[Mobile App]
        API[API Consumers]
    end

    subgraph Backend
        Gateway[API Gateway]
        Auth[Auth Module]
        Users[Users Module]
        Currencies[Currencies Module]
        Transactions[Transactions Module]
        ExchangeRates[Exchange Rates Module]
        Admin[Admin Module]
        Notifications[Notifications Module]
    end

    subgraph Database
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis Cache)]
    end

    subgraph External
        Stellar[Stellar Network]
        Mailgun[Mailgun]
        Firebase[Firebase]
        RateProvider[Exchange Rate Provider]
    end

    Web --> Gateway
    Mobile --> Gateway
    API --> Gateway
    
    Gateway --> Auth
    Gateway --> Users
    Gateway --> Currencies
    Gateway --> Transactions
    Gateway --> ExchangeRates
    Gateway --> Admin
    Gateway --> Notifications
    
    Auth --> PostgreSQL
    Users --> PostgreSQL
    Currencies --> PostgreSQL
    Transactions --> PostgreSQL
    ExchangeRates --> Redis
    Notifications --> PostgreSQL
    
    Transactions --> Stellar
    Notifications --> Mailgun
    Notifications --> Firebase
    ExchangeRates --> RateProvider

• JWT-based authentication and authorization
• Role-based access control (Admin, User, Tutor)
• Multi-currency exchange system
• Blockchain integration with Stellar smart contracts
• Real-time and historical transactions tracking
• Modular, scalable NestJS architecture
• Exportable transaction data (CSV, Excel, PDF)

nexafx-backend/
├── src/
│   ├── admin/                # Admin panel and controls
│   ├── audit-logs/           # Audit trail and logging
│   ├── auth/                 # JWT authentication & authorization
│   ├── beneficiaries/        # Beneficiary management
│   ├── blockchain/           # Stellar blockchain integration
│   ├── common/               # Shared guards, interceptors, decorators, services
│   ├── currencies/           # Fiat and crypto currency management
│   ├── database/             # Database seeding scripts
│   ├── exchange-rates/       # Real-time exchange rate providers
│   ├── fees/                 # Transaction fee management
│   ├── health/               # Health check endpoints
│   ├── kyc/                  # KYC/AML compliance
│   ├── notifications/        # Push & email notifications
│   ├── otps/                 # One-time passwords for 2FA
│   ├── push-notifications/   # Firebase push notifications
│   ├── rate-alerts/          # Rate change alerts (utility)
│   ├── receipts/             # Transaction receipts
│   ├── referrals/            # Referral program
│   ├── scheduled-jobs/       # Background scheduled tasks
│   ├── tokens/               # Refresh token management (utility)
│   ├── transactions/         # Transaction processing & tracking
│   ├── two-factor/           # Two-factor authentication
│   ├── users/                # User management (CRUD, roles, profiles)
│   ├── app.module.ts         # Root application module
│   ├── app.controller.ts     # Root application controller
│   ├── app.service.ts        # Root application service
│   └── main.ts               # Application entry point
├── migrations/               # TypeORM migration files
├── test/                     # E2E and integration tests
├── .env.example              # Environment configuration template
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

• Backend Framework: NestJS 11, TypeScript 5.7
• Database ORM: TypeORM 0.3 (PostgreSQL)
• Authentication: JWT (Passport.js), Bcrypt, TOTP
• Blockchain: Stellar SDK with Horizon API integration
• Background Jobs: NestJS Schedule (@nestjs/schedule)
• Notifications: Mailgun (email), Firebase (push notifications)
• Rate Limiting: NestJS Throttler
• Documentation: Swagger/OpenAPI
• Testing: Jest, Supertest
• Code Quality: ESLint, Prettier

• Node.js: v20+ (LTS recommended)
• Docker & Docker Compose: For running PostgreSQL
• npm: v9+ (comes with Node.js)
• Git: For version control

The fastest way to get started is using our automated setup script:

# Clone the repository
git clone https://github.com/Nexacore-Org/NexaFx-backend.git
cd NexaFx-backend

# Run the setup script (does everything for you!)
./scripts/setup-dev.sh

# Start the application
npm run start:dev

If you prefer to set up manually:

git clone https://github.com/Nexacore-Org/NexaFx-backend.git
cd NexaFx-backend

npm ci

Copy the .env.example file and create a .env file:

cp .env.example .env

Edit .env and configure your variables (see Environment Variables section below).

docker-compose up -d

npm run typeorm:migration:run

npm run start:dev

• API Docs: Visit http://localhost:3000/api/docs for Swagger UI
• Health Check: http://localhost:3000/health
• Run Tests: npm run test
• Run Lint: npm run lint
• Format Code: npm run format

Copy .env.example to .env and configure the following variables:

# Unit & Integration
npm run test

# E2E
npm run test:e2e

# Coverage
npm run test:cov

The application implements role-based access control (RBAC) with the following roles:

• USER: Can perform standard exchange operations, manage own profile, view transactions
• ADMIN: Full control of all resources, user management, configuration, audit logs
• SUPER_ADMIN: System-level administrative access — manages managed admins, platform configuration, and elevated role assignments via src/super-admin/

Guards are applied at controller and route levels using custom decorators (@RequireRole(), @Permissions()) and NestJS Guards.

The codebase contains 150+ module directories. The following table lists the core modules that are fully implemented and integrated. Scaffold-stub modules (those containing NotImplementedException placeholders) are not listed here as complete.

Swagger/OpenAPI documentation is available when the backend is running:

• URL: http://localhost:3000/api/docs
• Features: Interactive API explorer, request/response examples, schema definitions
• Auto-generated from NestJS decorators

Stellar Network provides the foundation for trustless, fast international transfers:

• Smart Contracts: Rust-based contracts deployed on Stellar
• Horizon API: Communication layer for account, ledger, and transaction queries
• Asset Creation: Native and custom asset support
• Multi-Signature Accounts: Enhanced security for hot wallets
• Transaction Flow: NestJS service → Stellar SDK → Horizon → Ledger

Current implementation:

• Account creation and funding
• Asset issuance
• Payment operations
• Transaction signing and submission
• Advanced: path payments, atomic swaps

npm run test           # Run all tests
npm run test:watch    # Watch mode (re-run on file changes)
npm run test:cov      # Generate coverage report

Test files follow the pattern: *.spec.ts
Coverage reports are generated in coverage/ directory

npm run test:e2e       # Run end-to-end tests
npm run test:debug     # Debug mode (use Chrome DevTools on port 9229)

• NODE_ENV — runtime environment. Allowed values: development, staging, production, test.
• PORT — application port, default 3000.
• DATABASE_URL — PostgreSQL connection string.
• JWT_SECRET — JWT signing secret, minimum 32 characters.
• JWT_EXPIRES_IN — JWT expiration time, e.g. 15m, 1h, 7d.
• ALLOWED_ORIGINS — comma-separated allowed CORS origins.

• GET /
• GET /health

This platform supports real-time updates via two complementary transports:

1. Socket.IO Gateways (src/gateways/): Optimized for high-throughput WebSocket clients and exchange rate feeds.
2. GraphQL Subscriptions (src/graphql-subscriptions/): Powered by graphql-ws, sharing underlying event streams with gateways for Apollo Client consumers with strict JWT authentication boundaries.