BIMP v2 API

Business Investment Management Platform - A comprehensive real estate investment management backend built with NestJS.

Overview

BIMP (Business Investment Management Platform) is a multi-tenant SaaS platform designed for real estate agencies to manage their properties, sales, commissions, investments, and client relationships. The platform supports hierarchical commission structures, payment processing, and comprehensive reporting.

Features

• Multi-Tenancy: Complete tenant isolation with agency-based data segregation
• User Management: Role-based access control (SUPER_ADMIN, BUSINESS, ADMIN, CLIENT, REALTOR)
• Product Management: Land, buildings, and investment products with pricing and payment plans
• Sales & Payments: Sales tracking with installment payment support via Paystack
• Commission System: Hierarchical commission rules, split policies, and promotions
• Investment Management: Investment products with user investment tracking
• Wallet & Transactions: Digital wallets with transaction history
• Document Generation: Template-based document generation
• Notifications: Email notifications with customizable templates
• File Storage: Cloudinary integration for file uploads

Tech Stack

• Framework: NestJS v9 with Express adapter
• Language: TypeScript
• Database: PostgreSQL with TypeORM
• Caching: Redis
• Authentication: JWT with Passport
• Authorization: CASL-based authority system
• File Storage: Cloudinary
• Payment Processing: Paystack
• API Documentation: Swagger/OpenAPI
• Internationalization: nestjs-i18n

Project Structure

src/
├── common/                    # Shared utilities, decorators, and base classes
│   ├── decorators/           # Custom decorators (auth, validation)
│   ├── enumerations/         # Application enums
│   ├── filters/              # Exception filters
│   ├── logger/               # Logging service
│   └── utils/                # Utility functions and constants
├── config/                    # Configuration modules
├── database/                  # Database setup
│   ├── migrations/           # TypeORM migrations
│   ├── redis/                # Redis service
│   └── seeders/              # Database seeders
├── events/                    # Event listeners and subscribers
├── i18n/                      # Internationalization files
└── modules/                   # Feature modules
    ├── commission-domain/    # Commission management
    ├── document-domain/      # Document templates and generation
    ├── financial-domain/     # Wallets and transactions
    ├── integration/          # Third-party integrations (Paystack)
    ├── investment-domain/    # Investment products and user investments
    ├── multi-tenancy-domain/ # Agency/tenant management
    ├── notification/         # Email and notifications
    ├── product-domain/       # Products, sales, payments
    ├── security/             # Authentication and authorization
    ├── settings-domain/      # Application settings
    ├── storage/              # File storage (Cloudinary)
    └── user-domain/          # Users, clients, realtors

Getting Started

Prerequisites

• Node.js v18+
• PostgreSQL 14+
• Redis 6+
• npm or yarn

Installation

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Configure your environment variables in .env

Environment Variables

Key environment variables to configure:

# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=bimp_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=1d

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Paystack
PAYSTACK_SECRET_KEY=your_paystack_secret

Database Setup

# Run migrations
npm run migration:run

# Seed initial data
npm run seed

Running the Application

# Development mode (with hot-reload)
npm run start:dev

# Debug mode
npm run start:debug

# Production mode
npm run build
npm run start:prod

API Documentation

Once the application is running, access the Swagger documentation at:

http://localhost:3000/api/docs

Available Scripts

Command	Description
npm run start:dev	Start in development mode with hot-reload
npm run start:debug	Start in debug mode with Node inspector
npm run build	Compile TypeScript to dist/
npm run test	Run unit tests
npm run test:watch	Run tests in watch mode
npm run test:cov	Generate test coverage report
npm run test:e2e	Run end-to-end tests
npm run lint	Run ESLint with auto-fix
npm run format	Run Prettier formatting
npm run migration:run	Run pending migrations
npm run migration:revert	Revert last migration
npm run seed	Run database seeders

User Roles

Role	Description
SUPER_ADMIN	Platform super administrator with full access
BUSINESS	Agency/business owner with agency-wide access
ADMIN	Agency administrator for day-to-day operations
CLIENT	End-user/buyer of properties
REALTOR	Real estate agent who facilitates sales

Authorization

The platform uses a CASL-based authority system. Protected endpoints require specific authorities:

@UseGuards(JwtAuthGuard, AuthorityGuard)
@RequireAuthorities('SUPER_ADMIN')
@Post('/create')
async createAgency(@Body() dto: CreateAgencyDto) {
  // Only SUPER_ADMIN can access
}

API Versioning

All API endpoints are versioned:

/api/v1/agency
/api/v1/user
/api/v1/product

Multi-Tenancy

The platform implements multi-tenancy at the database level:

• Each agency operates as an isolated tenant
• All entities include a tenant_id for data isolation
• SUPER_ADMIN can access all tenants
• Other roles are scoped to their assigned tenant

Contributing

1. Create a feature branch from master
2. Make your changes following the existing code patterns
3. Write/update tests as needed
4. Submit a pull request

License

This project is proprietary software. All rights reserved.