development setup

Development Setup Guide

Complete guide for setting up the Valtronics development environment

---

Overview

This guide provides comprehensive instructions for setting up a complete development environment for the Valtronics system, including backend, frontend, database, and supporting services.

---

Prerequisites

System Requirements

• Operating System: Linux (Ubuntu 20.04+), macOS (10.15+), or Windows 10+ with WSL2
• RAM: 8GB minimum, 16GB recommended
• Storage: 50GB free space minimum
• Processor: 4-core CPU minimum, 8-core recommended

Software Requirements

• Python: 3.8+ (3.10+ recommended)
• Node.js: 16.0+ (18.0+ recommended)
• npm: 7.0+ or yarn 1.22+
• Git: 2.0+
• Docker: 20.0+ (for containerized development)
• Docker Compose: 1.29+ (for multi-container development)
• VS Code: Recommended IDE (or any preferred IDE)

Optional Tools

• PostgreSQL: 12+ (for production-like development)
• Redis: 6+ (for caching and session management)
• Postman: For API testing
• DBeaver: Database management tool
• Redis Desktop Manager: Redis GUI tool

---

Environment Setup

1. Clone the Repository

# Clone the Valtronics repository
git clone https://github.com/valtronics/valtronics.git
cd valtronics

# Verify repository structure
ls -la

2. Backend Development Setup

Python Environment Setup

# Navigate to backend directory
cd backend

# Create Python virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Verify installation
python -c "import fastapi; print('FastAPI installed successfully')"
python -c "import sqlalchemy; print('SQLAlchemy installed successfully')"

Development Dependencies

Create requirements-dev.txt if it doesn't exist:

# Testing
pytest==7.4.0
pytest-asyncio==0.21.0
pytest-cov==4.1.0
pytest-mock==3.11.1
httpx==0.24.1

# Code Quality
black==23.7.0
isort==5.12.0
flake8==6.0.0
mypy==1.5.1
pre-commit==3.3.3

# Development Tools
python-dotenv==1.0.0
watchdog==3.0.0
ipython==8.14.0
jupyter==1.0.0

# Documentation
mkdocs==1.5.3
mkdocs-material==9.1.21
mkdocs-mermaid2-plugin==1.1.1

Environment Configuration

# Copy environment template
cp .env.example .env

# Edit environment file for development
nano .env

Development .env configuration:

# Development Settings
DEBUG=true
ENVIRONMENT=development

# Database
DATABASE_URL=sqlite:///./valtronics_dev.db

# Security (use development keys only!)
SECRET_KEY=dev-secret-key-change-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# CORS (allow all origins in development)
BACKEND_CORS_ORIGINS=["http://localhost:3000", "http://127.0.0.1:3000"]

# Redis (optional for development)
REDIS_URL=redis://localhost:6379/0

# OpenAI (optional)
OPENAI_API_KEY=your-openai-api-key

# Logging
LOG_LEVEL=DEBUG
LOG_FORMAT=json

3. Frontend Development Setup

Node.js Environment Setup

# Navigate to frontend directory
cd ../frontend

# Install Node.js dependencies
npm install

# Verify installation
node --version
npm --version

# Install additional development tools
npm install --save-dev @typescript-eslint/eslint-plugin
npm install --save-dev @typescript-eslint/parser
npm install --save-dev eslint-plugin-react-hooks
npm install --save-dev prettier

Frontend Environment Configuration

# Copy environment template
cp .env.example .env

# Edit environment file for development
nano .env

Development .env configuration:

# API Configuration
REACT_APP_API_URL=http://localhost:8000
REACT_APP_WS_URL=ws://localhost:8000/ws

# Application
REACT_APP_NAME=Valtronics
REACT_APP_VERSION=1.0.0

# Feature Flags
REACT_APP_ENABLE_AI_FEATURES=true
REACT_APP_ENABLE_REAL_TIME=true
REACT_APP_ENABLE_ANALYTICS=true
REACT_APP_ENABLE_DARK_MODE=true

# Development Settings
REACT_APP_DEV_SERVER_PORT=3000
REACT_APP_FAST_REFRESH=true
REACT_APP_DISABLE_ESLINT=false

4. Database Setup

SQLite (Default Development)

# Navigate to backend directory
cd ../backend

# Initialize database
python init_database.py

# Create sample data
python create_sample_data.py

# Verify database
ls -la valtronics_dev.db

PostgreSQL (Production-like Development)

# Install PostgreSQL
sudo apt-get install postgresql postgresql-contrib

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql

SQL commands:

CREATE DATABASE valtronics_dev;
CREATE USER valtronics_dev WITH PASSWORD 'dev_password';
GRANT ALL PRIVILEGES ON DATABASE valtronics_dev TO valtronics_dev;
ALTER USER valtronics_dev CREATEDB;
\q

Update .env for PostgreSQL:

DATABASE_URL=postgresql://valtronics_dev:dev_password@localhost:5432/valtronics_dev

5. Redis Setup (Optional)

# Install Redis
sudo apt-get install redis-server

# Start Redis service
sudo systemctl start redis-server
sudo systemctl enable redis-server

# Test Redis connection
redis-cli ping

---

IDE Configuration

VS Code Setup

Recommended Extensions

{
  "recommendations": [
    "ms-python.python",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-json",
    "redhat.vscode-yaml",
    "ms-vscode-remote.remote-containers",
    "ms-vscode.vscode-docker",
    "ms-vscode.vscode-git",
    "ms-vscode.vscode-jupyter",
    "ms-vscode.vscode-tslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense",
    "ms-vscode.vscode-live-server"
  ]
}

Workspace Settings

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "./backend/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": false,
  "python.linting.flake8Enabled": true,
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--line-length", "88"],
  "python.sortImports.args": ["--profile", "black"],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "eslint.workingDirectories": ["frontend"],
  "prettier.configPath": "frontend/.prettierrc",
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    "**/node_modules": true,
    "**/venv": true,
    "**/.pytest_cache": true
  }
}

Debug Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: FastAPI",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/backend/main_sqlite.py",
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}/backend",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/backend"
      },
      "args": ["--reload"]
    },
    {
      "name": "Python: Pytest",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${workspaceFolder}/backend/tests", "-v"],
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}/backend"
    },
    {
      "name": "Node: React App",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}/frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["start"]
    }
  ]
}

---

Development Workflow

1. Start Development Servers

Backend Server

# Terminal 1: Start backend
cd backend
source venv/bin/activate
python main_sqlite.py --reload

Frontend Server

# Terminal 2: Start frontend
cd frontend
npm start

Optional Services

# Terminal 3: Redis (if using)
redis-server

# Terminal 4: PostgreSQL (if using)
sudo systemctl start postgresql

2. Development Tasks

Code Quality Tools

# Backend code formatting
cd backend
black app/
isort app/

# Frontend code formatting
cd frontend
npm run format
npm run lint:fix

Testing

# Backend tests
cd backend
pytest tests/ -v --cov=app

# Frontend tests
cd frontend
npm test
npm run test:coverage

Database Operations

# Reset database
cd backend
rm valtronics_dev.db
python init_database.py
python create_sample_data.py

# Run migrations
alembic upgrade head

---

Development Tools Configuration

Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Create pre-commit configuration
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-json
      - id: check-merge-conflict

  - repo: https://github.com/psf/black
    rev: 23.7.0
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: ["--profile", "black"]

  - repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.44.0
    hooks:
      - id: eslint
        files: \.(js|ts|tsx)$
        types: [file]
EOF

# Install pre-commit hooks
pre-commit install

Docker Development Setup

Development Dockerfile

# backend/Dockerfile.dev
FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8000

# Run the application
CMD ["python", "main_sqlite.py", "--reload"]

Docker Compose Development

# docker-compose.dev.yml
version: '3.8'

services:
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
      - /app/venv
    environment:
      - DATABASE_URL=sqlite:///./valtronics_dev.db
      - DEBUG=true
    depends_on:
      - postgres
      - redis

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - REACT_APP_API_URL=http://localhost:8000
      - REACT_APP_WS_URL=ws://localhost:8000/ws
    depends_on:
      - backend

  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: valtronics_dev
      POSTGRES_USER: valtronics_dev
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Docker Development Commands

# Build and start development containers
docker-compose -f docker-compose.dev.yml up --build

# Run in detached mode
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f backend

# Stop containers
docker-compose -f docker-compose.dev.yml down

---

Testing Setup

Backend Testing Configuration

pytest Configuration

Create backend/pytest.ini:

[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = 
    -v
    --cov=app
    --cov-report=html
    --cov-report=term-missing
    --cov-fail-under=80
    --strict-markers
    --disable-warnings
markers =
    unit: Unit tests
    integration: Integration tests
    slow: Slow tests
    api: API tests
    database: Database tests

Test Structure

backend/tests/
├── conftest.py              # Pytest configuration
├── unit/                    # Unit tests
│   ├── test_models.py
│   ├── test_services.py
│   └── test_utils.py
├── integration/             # Integration tests
│   ├── test_api.py
│   ├── test_database.py
│   └── test_websocket.py
├── fixtures/                # Test fixtures
│   ├── __init__.py
│   ├── devices.py
│   ├── telemetry.py
│   └── alerts.py
└── utils/                   # Test utilities
    ├── __init__.py
    ├── test_client.py
    └── database.py

Test Fixtures Example

# tests/conftest.py
import pytest
import asyncio
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from app.db.session import Base
from app.core.config import settings

@pytest.fixture(scope="session")
def test_db():
    """Create test database"""
    engine = create_engine(
        settings.DATABASE_URL,
        connect_args={"check_same_thread": False}
    )
    
    Base.metadata.create_all(engine)
    
    TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
    
    yield TestingSessionLocal
    
    Base.metadata.drop_all(engine)

@pytest.fixture
def test_client(test_db):
    """Create test client"""
    from app.main_sqlite import app
    
    app.dependency_overrides[get_db] = lambda: test_db
    
    with TestClient(app) as client:
        yield client

@pytest.fixture
def sample_device(test_db):
    """Create sample device for testing"""
    from app.models.device import Device
    
    device = Device(
        name="Test Device",
        device_id="TEST-001",
        device_type="sensor",
        manufacturer="Test Corp",
        model="TC-1000",
        firmware_version="1.0.0",
        location="Test Lab",
        status="online"
    )
    
    test_db.add(device)
    test_db.commit()
    test_db.refresh(device)
    
    return device

Frontend Testing Configuration

Jest Configuration

Update frontend/package.json:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage",
    "test:ci": "jest --ci --coverage --watchAll=false"
  },
  "jest": {
    "testEnvironment": "jsdom",
    "setupFilesAfterEnv": ["<rootDir>/src/setupTests.js"],
    "moduleNameMapping": {
      "^@/(.*)$": "<rootDir>/src/$1"
    },
    "collectCoverageFrom": [
      "src/**/*.{js,jsx,ts,tsx}",
      "!src/**/*.d.ts",
      "!src/index.js",
      "!src/reportWebVitals.js"
    ],
    "coverageThreshold": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

Test Setup File

Create frontend/src/setupTests.js:

import '@testing-library/jest-dom';
import { configure } from '@testing-library/react';

// Configure testing library
configure({ testIdAttribute: 'data-testid' });

// Mock WebSocket
global.WebSocket = jest.fn(() => ({
  addEventListener: jest.fn(),
  removeEventListener: jest.fn(),
  send: jest.fn(),
  close: jest.fn(),
  readyState: WebSocket.OPEN,
}));

// Mock Intersection Observer
global.IntersectionObserver = jest.fn(() => ({
  observe: jest.fn(),
  unobserve: jest.fn(),
  disconnect: jest.fn(),
}));

// Mock ResizeObserver
global.ResizeObserver = jest.fn(() => ({
  observe: jest.fn(),
  unobserve: jest.fn(),
  disconnect: jest.fn(),
}));

---

Debugging Setup

Backend Debugging

Python Debugger Configuration

# Add to your code for debugging
import pdb; pdb.set_trace()

# Or use ipdb for better debugging
import ipdb; ipdb.set_trace()

VS Code Debugging

Use the debug configuration provided in the IDE setup section.

Frontend Debugging

Chrome DevTools Setup

// Add to your code for debugging
console.log('Debug point:', data);
debugger; // Breakpoint in browser

// React DevTools
if (process.env.NODE_ENV === 'development') {
  const { ReactDevTools } = require('react-devtools');
  ReactDevTools.instrument();
}

---

Performance Monitoring

Development Performance Tools

Backend Profiling

# Add to main_sqlite.py
import cProfile
import pstats

@app.middleware("http")
async def profile_middleware(request: Request, call_next):
    if request.query.get("profile"):
        profiler = cProfile.Profile()
        profiler.enable()
        
        response = await call_next(request)
        
        profiler.disable()
        
        stats = pstats.Stats(profiler)
        stats.sort_stats('cumulative')
        
        # Save profiling results
        stats.dump_stats('profile_stats.prof')
        
        return response
    
    return await call_next(request)

Frontend Performance Monitoring

// Add to App.js
import React, { useEffect } from 'react';
import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals';

function sendToAnalytics(metric) {
  // Send to analytics service
  console.log('Performance metric:', metric);
}

export default function App() {
  useEffect(() => {
    getCLS(sendToAnalytics);
    getFID(sendToAnalytics);
    getFCP(sendToAnalytics);
    getLCP(sendToAnalytics);
    getTTFB(sendToAnalytics);
  }, []);

  return (
    // Your app content
    <div>Valtronics App</div>
  );
}

---

Common Development Issues

Backend Issues

Database Connection Errors

# Check database file permissions
ls -la valtronics_dev.db

# Recreate database
rm valtronics_dev.db
python init_database.py

Import Errors

# Check Python path
python -c "import sys; print(sys.path)"

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Port Conflicts

# Check port usage
netstat -tulpn | grep :8000
lsof -i :8000

# Kill process using port
sudo kill -9 <PID>

Frontend Issues

Module Resolution Errors

# Clear npm cache
npm cache clean --force

# Delete node_modules
rm -rf node_modules package-lock.json

# Reinstall
npm install

Build Errors

# Check for syntax errors
npm run build

# Fix ESLint errors
npm run lint:fix

# Fix TypeScript errors
npx tsc --noEmit

---

Development Best Practices

Code Organization

• Follow the established directory structure
• Use meaningful variable and function names
• Write modular, reusable code
• Add appropriate comments and documentation

Git Workflow

• Use feature branches for new development
• Commit frequently with descriptive messages
• Use pull requests for code review
• Keep main branch stable

Testing

• Write tests for new features
• Maintain high test coverage
• Test edge cases and error conditions
• Use descriptive test names

Documentation

• Document API endpoints with OpenAPI
• Add inline code comments
• Update README files
• Maintain up-to-date documentation

---

Support

For development support:

• Documentation: Code Structure
• Contributing: Contributing Guidelines
• Testing: Testing Guide
• Troubleshooting: Troubleshooting Guide
• Email: autobotsolution@gmail.com

---

© 2024 Software Customs Auto Bot Solution. All Rights Reserved.
Development Setup Guide v1.0