Developer Guide¶

This section provides development guides, API documentation, testing procedures, and setup instructions for developers working on the NexusAI platform.

Overview¶

The developer documentation includes:

Getting Started - Development environment setup
Backend Development - Backend service development
Frontend Development - UI application development
API Documentation - REST APIs and MCP tools
Testing - Unit, integration, and E2E testing
LocalStack - Local development environment

Available Documents¶

Backend Development¶

Backend README¶

Comprehensive guide to the backend service architecture, setup, and development.

📄 View Backend README

LocalStack Setup¶

Guide to setting up LocalStack for local development without AWS costs.

📄 View LocalStack Setup Guide

Additional Resources¶

Development Environment Setup¶

Prerequisites¶

Python: 3.11 or higher
Node.js: 18+ (for frontend)
Docker: Latest version
Git: Latest version
AWS CLI: Latest version (optional)

Backend Setup¶

Option 1: LocalStack (Recommended for Development)¶

# Clone repository
git clone <repository-url>
cd nexus-backend

# Start LocalStack
docker-compose -f docker-compose-localstack.yml up -d

# Setup environment
cp .env.localstack.example .env.local
export USE_LOCALSTACK=true
export LOCALSTACK_HOST=localhost
export LOCALSTACK_PORT=4566

# Install dependencies
pip install -r requirements.txt

# Initialize LocalStack resources
python -m tests.localstack_automation.run_automation --setup

# Start gateway
./gateway.sh start

# Verify
./gateway.sh test

Option 2: Real AWS¶

# Configure AWS credentials
aws configure
# or
export AWS_PROFILE=your-profile

# Setup environment
export ENVIRONMENT=dev
export AWS_REGION=ap-southeast-1

# Install dependencies
pip install -r requirements.txt

# Start gateway
./gateway.sh start

Frontend Setup¶

# Clone repository
git clone <repository-url>
cd nexus-ui

# Install dependencies
npm install

# Start development server
npm run dev

Development Workflow¶

1. Create Feature Branch¶

git checkout -b feature/your-feature-name

2. Implement Changes¶

Write code following project conventions
Add tests for new functionality
Update documentation as needed

3. Run Tests¶

# Backend tests
pytest tests/unit/ -v
pytest tests/integration/ -v
pytest tests/bdd/ -v

# Frontend tests
npm test

4. Commit Changes¶

git add .
git commit -m "feat: add your feature description"

5. Push and Create PR¶

git push origin feature/your-feature-name
# Create pull request on GitHub

Testing¶

Backend Testing¶

Unit Tests¶

Test individual components in isolation:

pytest tests/unit/ -v

Integration Tests¶

Test component interactions with LocalStack:

USE_LOCALSTACK=true pytest tests/integration/ -v

BDD Tests¶

Behavior-driven development tests:

pytest tests/bdd/ -v --gherkin-terminal-reporter

E2E Tests¶

End-to-end testing:

pytest tests/e2e/ -v

Frontend Testing¶

Unit Tests¶

npm run test:unit

Component Tests¶

npm run test:component

E2E Tests¶

npm run test:e2e

API Development¶

REST APIs¶

The platform exposes REST APIs via FastAPI:

from fastapi import APIRouter, Depends
from src.models import Journey

router = APIRouter()

@router.post("/api/v1/journeys")
async def create_journey(journey: Journey):
    # Implementation
    pass

MCP Tools¶

MCP tools for AI agent integration:

from src.tools.base_tool import MCPTool

class MyTool(MCPTool):
    def execute(self, params):
        # Implementation
        pass

Code Standards¶

Python Code Style¶

Follow PEP 8
Use type hints
Write docstrings
Max line length: 100 characters

from typing import List, Optional

def process_call(
    call_id: str,
    options: Optional[dict] = None
) -> dict:
    """
    Process a single call.

    Args:
        call_id: The call identifier
        options: Optional processing options

    Returns:
        Processing result dictionary
    """
    pass

TypeScript Code Style¶

Use TypeScript strict mode
Follow ESLint rules
Use functional components
Implement proper typing

interface CallData {
  id: string;
  timestamp: number;
  duration: number;
}

const ProcessCall: React.FC<{ call: CallData }> = ({ call }) => {
  // Implementation
};

Debugging¶

Backend Debugging¶

Using Python Debugger¶

import pdb; pdb.set_trace()

VSCode Debugging¶

{
  "type": "python",
  "request": "launch",
  "name": "Gateway",
  "program": "${workspaceFolder}/mcp_http_gateway.py",
  "console": "integratedTerminal"
}

Logging¶

import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
logger.debug("Debug message")

Frontend Debugging¶

Browser DevTools¶

Use React Developer Tools
Check Network tab for API calls
Use Console for logs

VSCode Debugging¶

{
  "type": "chrome",
  "request": "launch",
  "name": "Launch Chrome",
  "url": "http://localhost:3000",
  "webRoot": "${workspaceFolder}/src"
}

Common Development Tasks¶

Add a New API Endpoint¶

Create endpoint in src/apis/
Add route to gateway
Write tests
Update API documentation

Add a New MCP Tool¶

Create tool class in src/tools/
Implement execute method
Register tool in gateway
Write tests
Update tool documentation

Add a New Transformation Stage¶

Create stage class in src/stages/
Inherit from BaseStage
Implement process method
Add stage configuration
Write tests

Update Database Schema¶

Modify table definition
Create migration script
Update models
Test with LocalStack
Document changes

Performance Optimization¶

Backend Optimization¶

Use async/await for I/O operations
Implement caching where appropriate
Optimize database queries
Use batch operations
Profile with cProfile

Frontend Optimization¶

Code splitting
Lazy loading
Memoization
Virtual scrolling
Bundle optimization

Security Best Practices¶

Backend Security¶

Validate all inputs
Use parameterized queries
Store secrets securely
Implement rate limiting
Use HTTPS only

Frontend Security¶

Sanitize user inputs
Implement CSRF protection
Use Content Security Policy
Secure authentication tokens
Regular dependency updates

Documentation¶

Code Documentation¶

Write clear docstrings
Add inline comments for complex logic
Update README files
Document API changes

API Documentation¶

Use OpenAPI/Swagger
Provide examples
Document error responses
Keep documentation in sync with code

Resources¶

Internal Documentation¶

External Resources¶

Getting Help¶

📖 Check existing documentation
🔍 Search codebase for examples
💬 Ask in team chat
🐛 Check issue tracker
📝 Create detailed bug reports

← Back to Home | ← Previous: Operational Documentation

Developer Guide¶

Overview¶

Available Documents¶

Backend Development¶

Backend README¶

LocalStack Setup¶

Additional Resources¶

Requirements Documentation¶

MCP Tools Documentation¶

LocalStack Documentation¶

Claude Integration¶

Development Environment Setup¶

Prerequisites¶

Backend Setup¶

Option 1: LocalStack (Recommended for Development)¶

Option 2: Real AWS¶

Frontend Setup¶

Development Workflow¶

1. Create Feature Branch¶

2. Implement Changes¶

3. Run Tests¶

4. Commit Changes¶

5. Push and Create PR¶

Testing¶

Backend Testing¶

Unit Tests¶

Integration Tests¶

BDD Tests¶

E2E Tests¶

Frontend Testing¶

Unit Tests¶

Component Tests¶

E2E Tests¶

API Development¶

REST APIs¶

MCP Tools¶

Code Standards¶

Python Code Style¶

TypeScript Code Style¶

Debugging¶

Backend Debugging¶

Using Python Debugger¶

VSCode Debugging¶

Logging¶

Frontend Debugging¶

Browser DevTools¶

VSCode Debugging¶

Common Development Tasks¶

Add a New API Endpoint¶

Add a New MCP Tool¶

Add a New Transformation Stage¶

Update Database Schema¶

Performance Optimization¶

Backend Optimization¶

Frontend Optimization¶

Security Best Practices¶

Backend Security¶

Frontend Security¶

Documentation¶

Code Documentation¶

API Documentation¶

Resources¶

Internal Documentation¶

External Resources¶

Getting Help¶