ChargeHive Backend

ChargeHive is a peer-to-peer EV charging platform that connects electric vehicle owners with homeowners who have charging stations. This backend API provides REST endpoints for user authentication, provider management, session booking, payment processing, and blockchain integration using Flow blockchain.

About the Project

ChargeHive solves the problem of limited EV charging infrastructure by enabling homeowners to rent out their private chargers. The platform includes:

• User and provider authentication with Supabase
• Service management for charging stations
• Session booking and scheduling
• Payment processing
• Flow blockchain integration for transparent charging data and rewards
• CHToken reward system for providers

Steps to Run Locally

Prerequisites

• Node.js 18.x or higher
• npm or yarn
• Supabase account
• Flow blockchain testnet account (optional for full functionality)

Installation

1. Clone the repository

git clone https://github.com/Charge-Hive/Chargehive-backend.git
cd Chargehive-backend

2. Install dependencies

npm install

3. Set up environment variables Create a .env file in the root directory:

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_KEY=your_supabase_service_key

# JWT Configuration
JWT_SECRET=your_jwt_secret

# Flow Blockchain Configuration
FLOW_PRIVATE_KEY=your_flow_private_key
FLOW_SERVICE_ACCOUNT_ADDRESS=your_flow_account_address
ADAPTER_ID=your_adapter_id

# Application Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=debug

4. Run the application

# Development mode with hot reload
npm run start:dev

# Production mode
npm run build
npm run start:prod

The API will be available at http://localhost:3000/api

API documentation (Swagger) will be available at http://localhost:3000/api/docs

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

Project Structure

Chargehive-backend/
├── src/
│   ├── auth/                    # Authentication module (JWT, password hashing)
│   │   ├── auth.service.ts
│   │   ├── auth.service.spec.ts
│   │   └── auth.module.ts
│   ├── common/                  # Shared utilities
│   │   ├── dto/                 # Error response DTOs
│   │   ├── filters/             # Global exception filters
│   │   │   ├── http-exception.filter.ts
│   │   │   └── validation-exception.filter.ts
│   │   ├── interceptors/        # Request logging interceptor
│   │   │   └── logging.interceptor.ts
│   │   └── logger/              # Winston logger service
│   │       ├── logger.service.ts
│   │       └── logger.module.ts
│   ├── flow/                    # Flow blockchain integration
│   │   └── flow.service.ts
│   ├── health/                  # Health check endpoint
│   │   ├── health.controller.ts
│   │   └── health.module.ts
│   ├── payments/                # Payment processing
│   │   ├── payments.service.ts
│   │   └── payments.controller.ts
│   ├── provider/                # Provider management
│   │   ├── provider.service.ts
│   │   └── provider.controller.ts
│   ├── services/                # Charging service management
│   │   ├── services.service.ts
│   │   └── services.controller.ts
│   ├── sessions/                # Booking sessions
│   │   ├── sessions.service.ts
│   │   ├── sessions.service.spec.ts
│   │   └── sessions.controller.ts
│   ├── supabase/                # Supabase client configuration
│   │   └── supabase.service.ts
│   ├── user/                    # User management
│   │   ├── user.service.ts
│   │   └── user.controller.ts
│   ├── wallet/                  # Blockchain wallet management
│   │   ├── wallet.service.ts
│   │   └── wallet.controller.ts
│   ├── app.module.ts            # Root application module
│   └── main.ts                  # Application entry point
├── logs/                        # Application logs (daily rotation)
│   ├── application-YYYY-MM-DD.log
│   └── error-YYYY-MM-DD.log
├── .github/
│   └── workflows/
│       └── ci-cd.yml            # GitHub Actions CI/CD pipeline
├── jest.config.js               # Jest testing configuration
├── Procfile                     # Heroku deployment configuration
├── package.json
└── tsconfig.json

Continuous Integration & Deployment

CI/CD Pipeline

The project uses GitHub Actions for automated testing and deployment. The pipeline is defined in .github/workflows/ci-cd.yml.

CI Pipeline (Runs on every push and PR to main)

1. Install Dependencies: npm ci
2. Linting: npm run lint (non-blocking)
3. Testing: npm test - All unit tests must pass
4. Build: npm run build - TypeScript compilation
5. Coverage Upload: Test coverage reports uploaded as artifacts

CD Pipeline (Runs only on push to main, after tests pass)

1. Deploy to Heroku: Automated deployment using akhileshns/heroku-deploy
2. Health Check: Verifies deployment at /api/health endpoint
3. Auto Rollback: Automatically rolls back if health check fails

Testing Strategy

• Unit Tests: Testing individual services and controllers in isolation
  • Auth service: Password hashing, JWT generation/verification
  • Sessions service: Booking validation, availability checks
  • Health controller: Endpoint response validation
• Test Coverage: Configured to generate coverage reports
• CI Integration: Tests run automatically on every code push

Heroku Deployment

The Procfile defines the production start command:

web: npm run start:prod

Required Heroku Secrets (configured in GitHub repository secrets):

• HEROKU_API_KEY: Your Heroku API key
• HEROKU_APP_NAME: Your Heroku application name
• HEROKU_EMAIL: Your Heroku account email

Health Check Endpoint: /api/health

• Returns: { status: "ok", timestamp: "...", uptime: 123.45 }
• Used by CI/CD pipeline to verify successful deployment

Error Handling & Logging

• Global Exception Filters: Catch all errors and return user-friendly messages
• Error Codes: Standardized error codes (4xx for client errors, 5xx for server errors)
• Daily Log Rotation: Logs stored in logs/ directory with daily rotation
  • application-YYYY-MM-DD.log: All logs (info, warn, error)
  • error-YYYY-MM-DD.log: Error logs only
• Sensitive Data Protection: Passwords, tokens, and private keys are redacted from logs
• Request Logging: All HTTP requests logged with method, URL, response time, and status code

API Documentation

Once the application is running, visit:

• Swagger UI: http://localhost:3000/api/docs
• Health Check: http://localhost:3000/api/health

Technologies Used

• Framework: NestJS
• Language: TypeScript
• Database: Supabase (PostgreSQL)
• Authentication: Supabase Auth + JWT
• Blockchain: Flow blockchain
• Testing: Jest
• Logging: Winston with daily rotation
• CI/CD: GitHub Actions + Heroku
• Documentation: Swagger/OpenAPI