Skip to content

Quick Start Guide

Welcome to ABS Platform development! This guide will get you up and running with a local development environment in under 30 minutes.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

  • VS Code - Download from code.visualstudio.com
  • VS Code Extensions:
  • TypeScript and JavaScript Language Features
  • GraphQL: Language Feature Support
  • ESLint
  • Prettier - Code formatter
  • Docker

Project Setup

1. Clone the Repository

git clone https://github.com/OVES/abs-platform.git
cd abs-platform

2. Install Dependencies

# Install Node.js dependencies
npm install

# Verify installation
npm run verify

3. Environment Configuration

Create your local environment configuration:

# Copy environment template
cp .env.example .env.local

# Edit configuration (use your preferred editor)
code .env.local

Required Environment Variables: 

# Database Configuration
DATABASE_URL=postgresql://abs_user:abs_password@localhost:5432/abs_platform
REDIS_URL=redis://localhost:6379

# MQTT Configuration  
MQTT_BROKER_URL=mqtt://localhost:1883
MQTT_USERNAME=abs_platform
MQTT_PASSWORD=your_mqtt_password

# Authentication
JWT_SECRET=your_super_secret_jwt_key_here
JWT_EXPIRES_IN=24h

# External Integrations
ODOO_API_URL=http://localhost:8069
ODOO_DATABASE=abs_platform
ODOO_USERNAME=admin
ODOO_PASSWORD=admin

# Development Settings
NODE_ENV=development
LOG_LEVEL=debug

4. Start Infrastructure Services

Start the required infrastructure using Docker Compose:

# Start PostgreSQL, Redis, and MQTT broker
docker-compose up -d

# Verify services are running
docker-compose ps

5. Database Setup

Initialize the database schema and seed data:

# Run database migrations
npm run db:migrate

# Seed initial data
npm run db:seed

# Verify database setup
npm run db:verify

6. Start the Development Server

# Start the ABS Platform server
npm run dev

# Server should start on http://localhost:3000

7. Verify Installation

Open your browser and navigate to: - GraphQL Playground: http://localhost:3000/graphql - Health Check: http://localhost:3000/health - API Documentation: http://localhost:3000/docs

Development Workflow

Project Structure Overview

abs-platform/
├── src/                    # Source code
│   ├── agents/            # Agent system implementation
│   ├── core/              # Core services and utilities
│   ├── fsm/               # Finite State Machine engine
│   ├── orchestrator/      # System orchestration
│   ├── resolvers/         # GraphQL resolvers
│   └── services/          # Business services
├── models/                # Business models and configurations
│   └── bss/              # Battery Swap Service model
├── schema/                # GraphQL schema definitions
├── docs/                  # Documentation
├── tests/                 # Test files
└── scripts/               # Utility scripts

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- --testPathPattern=fsm

# Generate test coverage report
npm run test:coverage

Code Quality

# Check TypeScript compilation
npm run type-check

# Run ESLint
npm run lint

# Fix auto-fixable lint issues
npm run lint:fix

# Format code with Prettier
npm run format

# Run all quality checks
npm run quality-check

Development Commands

Essential Commands

# Development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Database operations
npm run db:migrate       # Run migrations
npm run db:rollback      # Rollback last migration
npm run db:seed          # Seed test data
npm run db:reset         # Reset database

# Testing
npm test                 # Run all tests
npm run test:unit        # Run unit tests only
npm run test:integration # Run integration tests only
npm run test:e2e         # Run end-to-end tests

Debugging

# Start server in debug mode
npm run dev:debug

# Debug with VS Code
# Use the "Launch Program" configuration in .vscode/launch.json

Working with the Codebase

Creating a New Agent

  1. Create Agent File: Create a new file in src/agents/ 

    // src/agents/my-new-agent.ts
import { AgentFunction, AgentContext } from './types';

export const myNewAgent: AgentFunction = async (
  request: any,
  servicePlan: any,
  context: AgentContext
) => {
  // Your agent logic here
  return {
    success: true,
    updatedState: context.state,
    outputs: []
  };
};

  2. Register Agent: Add to agent registry 

    // src/agents/plugin-registry.ts
import { myNewAgent } from './my-new-agent';

export const agentRegistry = {
  // ... existing agents
  myNewAgent,
};

  3. Write Tests: Create test file 

    // tests/agents/my-new-agent.test.ts
import { myNewAgent } from '../../src/agents/my-new-agent';

describe('myNewAgent', () => {
  it('should process requests correctly', async () => {
    // Your test implementation
  });
});

Creating GraphQL Resolvers

  1. Define Schema: Add to schema/abs.graphql 

    type Mutation {
  executeMyOperation(input: MyOperationInput!): MyOperationResult!
}

input MyOperationInput {
  servicePlanId: ID!
  operationData: JSON
}

type MyOperationResult {
  success: Boolean!
  message: String
}

  2. Implement Resolver: Add to src/resolvers/ 

    // src/resolvers/my-operation.ts
export const myOperationResolver = async (
  parent: any,
  args: { input: MyOperationInput },
  context: GraphQLContext
) => {
  // Your resolver logic here
  return {
    success: true,
    message: "Operation completed successfully"
  };
};

Working with FSMs

  1. FSM Definition: Create FSM configuration in models/*/fsm-definitions/
  2. Load FSM: Use the FSM engine to load and execute 
    import { FSMEngine } from '../src/fsm/engine';

const fsmEngine = new FSMEngine();
const result = await fsmEngine.processTransition(
  currentState,
  inputSignal,
  context
);

Integration Testing

Create integration tests for complete workflows:

// tests/integration/service-workflow.test.ts
describe('Service Workflow Integration', () => {
  it('should complete full service lifecycle', async () => {
    // 1. Create service plan
    const servicePlan = await createServicePlan(templateData);

    // 2. Process service request
    const result = await processServiceRequest(requestData);

    // 3. Verify state transitions
    expect(result.service_cycle_state).toBe('BATTERY_ISSUED');

    // 4. Complete service
    const completion = await completeService(servicePlan.id);
    expect(completion.status).toBe('COMPLETE');
  });
});

Common Development Tasks

Adding New Environment Variables

  1. Add to .env.example: Document the new variable
  2. Update Configuration: Add to src/config/index.ts
  3. Use in Code: Access via config object 
    import { config } from '../config';

const myValue = config.myNewVariable;

Database Schema Changes

  1. Create Migration: 

    npm run migration:create -- --name add_new_table

  2. Edit Migration File: Add your schema changes

  3. Run Migration: 
    npm run db:migrate

Adding New Dependencies

# Add runtime dependency
npm install package-name

# Add development dependency  
npm install --save-dev package-name

# Update TypeScript types if needed
npm install --save-dev @types/package-name

Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3000
lsof -ti:3000

# Kill the process (macOS/Linux)
kill -9 $(lsof -ti:3000)

# Or use a different port
PORT=3001 npm run dev

Database Connection Issues

# Check if PostgreSQL is running
docker-compose ps

# Restart database
docker-compose restart postgres

# Check database logs
docker-compose logs postgres

MQTT Connection Issues

# Check MQTT broker status
docker-compose logs mosquitto

# Test MQTT connection
npx mqtt pub -t 'test/topic' -m 'hello world' -h localhost

Getting Help

  • Documentation: Check /docs folder for detailed guides
  • Issues: Create GitHub issues for bugs or feature requests
  • Discussions: Use GitHub Discussions for questions
  • Code Review: Submit PRs for code review and feedback

Next Steps

Once you have the basic development environment running:

  1. Explore the Codebase: Review the existing agents and FSM implementations
  2. Run Example Workflows: Execute the example battery swap service workflows
  3. Read Architecture Docs: Understand the system design and patterns
  4. Join Development: Start contributing to the project
  1. Architecture Overview - Understand the system design
  2. FSM Engine Guide - Learn the state management patterns
  3. Agent Development Guide - Master the agent architecture

Happy coding! 🚀