title

description

Development Setup Guide

Introduction

This guide will help you set up a complete development environment for VisionFlow. Follow these steps to start contributing to the project.

Required Software

Tool	Minimum Version	Purpose
Git	2.30+	Version control
Node.js	16.x LTS or 18.x LTS	JavaScript runtime
npm	8.x+	Package management
Docker	20.10+	Container runtime
Docker Compose	1.29+	Multi-container orchestration

Optional Tools

Tool	Purpose
Python	3.9+ (if using Python components)
Go	1.19+ (if working on Go services)
PostgreSQL	14+ (for local database)
Redis	6+ (for caching)
Make	Build automation

Development Environment

Recommended IDE/Editor:

VS Code with extensions:
- ESLint
- Prettier
- Docker
- GitLens
- REST Client

Agent-Driven Development

SPARC workflow:

# Full TDD workflow
npx claude-flow sparc tdd "feature description"

# Individual phases
npx claude-flow sparc run spec-pseudocode "task"
npx claude-flow sparc run architect "task"
npx claude-flow sparc run integration "task"

Parallel agent execution (Claude Code Task tool):

// Spawn multiple agents concurrently
Task("Researcher", "Analyze requirements", "researcher")
Task("Architect", "Design system", "system-architect")
Task("Coder", "Implement features", "coder")
Task("Tester", "Create tests", "tester")

IntelliJ IDEA or WebStorm
Vim/Neovim with appropriate plugins

Repository Setup

1. Fork and Clone

# Fork the repository on GitHub first, then:

# Clone your fork
git clone https://github.com/YOUR-USERNAME/visionflow.git
cd visionflow

# Add upstream remote
git remote add upstream https://github.com/original-org/visionflow.git

# Verify remotes
git remote -v

2. Install Dependencies

# Install Node.js dependencies
npm install

# Or use yarn
yarn install

# Install Python dependencies (if applicable)
pip install -r requirements-dev.txt

# Install Go dependencies (if applicable)
go mod download

3. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env with your local settings
nano .env

Example .env configuration:

# Application
NODE-ENV=development
PORT=8080
API-PORT=9090

# Database
DB-HOST=localhost
DB-PORT=5432
DB-NAME=visionflow-dev
DB-USER=visionflow
DB-PASSWORD=dev-password

# Redis
REDIS-HOST=localhost
REDIS-PORT=6379

# Storage
STORAGE-TYPE=local
STORAGE-PATH=/tmp/visionflow-storage

# Logging
LOG-LEVEL=debug
LOG-FORMAT=pretty

# Development
HOT-RELOAD=true
DEBUG=true

Development Services

Starting Local Services

Option 1: Docker Compose (Recommended)

# Start all services
docker-compose -f docker-compose.dev.yml up -d

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

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

docker-compose.dev.yml includes:

PostgreSQL database
Redis cache
MinIO (S3-compatible storage)
MailHog (email testing)
Mock services

Option 2: Native Services

# Start PostgreSQL
sudo systemctl start postgresql

# Start Redis
sudo systemctl start redis

# Or use Docker for individual services
docker run -d --name visionflow-postgres \
  -e POSTGRES-DB=visionflow-dev \
  -e POSTGRES-USER=visionflow \
  -e POSTGRES-PASSWORD=dev-password \
  -p 5432:5432 \
  postgres:14

docker run -d --name visionflow-redis \
  -p 6379:6379 \
  redis:6-alpine

Database Setup

# Create database
createdb visionflow-dev

# Run migrations
npm run db:migrate

# Seed development data
npm run db:seed

# Reset database (careful!)
npm run db:reset

Building the Project

Development Build

# Build all packages
npm run build

# Build specific package
npm run build:api
npm run build:web
npm run build:cli

# Watch mode (auto-rebuild on changes)
npm run build:watch

Build Output Structure

dist/
├── api/          # API server build
├── web/          # Web UI build
├── cli/          # CLI tool build
└── shared/       # Shared libraries

Running the Application

Development Mode

# Start all services in development mode
npm run dev

# Start specific service
npm run dev:api    # API server only
npm run dev:web    # Web UI only
npm run dev:worker # Background worker only

Development features:

Hot module replacement (HMR)
Auto-restart on file changes
Source maps enabled
Verbose logging
Debug mode enabled

Accessing the Application

Service	URL	Purpose
Web UI	http://localhost:3030	Main interface
API	http://localhost:9090	REST API
API Docs	http://localhost:9090/docs	Swagger UI
GraphQL	http://localhost:9090/graphql	GraphQL playground
MailHog	http://localhost:8025	Email testing

Testing Setup

Test Database

# Create test database
createdb visionflow-test

# Configure test environment
cp .env.test.example .env.test

# Run migrations for test database
NODE-ENV=test npm run db:migrate

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- --grep "API"

# Watch mode
npm run test:watch

# E2E tests
npm run test:e2e

# Integration tests
npm run test:integration

Test Structure

tests/
├── unit/           # Unit tests
├── integration/    # Integration tests
├── e2e/           # End-to-end tests
├── fixtures/      # Test data
└── helpers/       # Test utilities

Code Quality Tools

Linting

# Run ESLint
npm run lint

# Auto-fix issues
npm run lint:fix

# Lint specific files
npm run lint -- src/api/**/*.js

ESLint Configuration (.eslintrc.js):

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error'
  }
};

Code Formatting

# Format all files
npm run format

# Check formatting
npm run format:check

# Format specific files
prettier --write "src/**/*.{js,ts,json,md}"

Prettier Configuration (.prettierrc):

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2
}

Type Checking

# Run TypeScript compiler
npm run typecheck

# Watch mode
npm run typecheck:watch

Pre-commit Hooks

We use Husky for Git hooks:

# Install husky
npm run prepare

# Hooks automatically run on:
# - pre-commit: lint, format, typecheck
# - pre-push: test

Development Workflow

Development Flow Diagram

flowchart TD
    A[Create Branch] --> B[Write Code]
    B --> C[Run Tests Locally]
    C --> D{Tests Pass?}
    D -->|No| B
    D -->|Yes| E[Commit Changes]
    E --> F[Push to Fork]
    F --> G[Create PR]
    G --> H[CI/CD Pipeline]
    H --> I{CI Pass?}
    I -->|No| B
    I -->|Yes| J[Code Review]
    J --> K{Approved?}
    K -->|No| B
    K -->|Yes| L[Merge to Main]

    style D fill:#FFE4B5
    style I fill:#FFE4B5
    style L fill:#90EE90

Branch Naming Convention

# Feature branches
git checkout -b feature/add-user-authentication

# Bug fixes
git checkout -b fix/resolve-upload-timeout

# Hotfixes
git checkout -b hotfix/security-patch

# Documentation
git checkout -b docs/update-api-guide

Commit Message Convention

Follow Conventional Commits:

# Format
<type>(<scope>): <description>

# Examples
feat(api): add user authentication endpoint
fix(web): resolve file upload timeout issue
docs(readme): update installation instructions
refactor(storage): improve S3 integration
test(api): add integration tests for auth
chore(deps): upgrade dependencies

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Debugging

VS Code Debug Configuration

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug API Server",
      "program": "${workspaceFolder}/src/api/index.js",
      "env": {
        "NODE-ENV": "development",
        "DEBUG": "visionflow:*"
      }
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node-modules/jest/bin/jest",
      "args": ["--runInBand", "--no-cache"],
      "console": "integratedTerminal"
    }
  ]
}

Debug Logging

// Enable debug logs
DEBUG=visionflow:* npm run dev

// Specific modules
DEBUG=visionflow:api,visionflow:db npm run dev

Chrome DevTools

# Start with Node inspector
node --inspect src/api/index.js

# Or with npm script
npm run dev:debug

Then open: chrome://inspect

Common Development Tasks

Adding a New API Endpoint

Define route in src/api/routes/
Create controller in src/api/controllers/
Add service logic in src/api/services/
Write tests in tests/unit/api/
Update API documentation

Adding a New Feature

Create feature branch
Implement feature with TDD approach
Add/update documentation
Run full test suite
Submit pull request

Updating Dependencies

# Check for outdated packages
npm outdated

# Update package
npm update package-name

# Update all packages (careful!)
npm update

# Check for security vulnerabilities
npm audit

# Fix vulnerabilities
npm audit fix

Performance Profiling

Node.js Profiling

# CPU profiling
node --prof src/api/index.js

# Memory profiling
node --inspect --expose-gc src/api/index.js

Application Metrics

# Start with metrics enabled
ENABLE-METRICS=true npm run dev

# Access metrics
curl http://localhost:9090/metrics

Environment Management

Multiple Environments

# Development
npm run dev

# Staging
NODE-ENV=staging npm start

# Production
NODE-ENV=production npm start

Environment Files

.env.example         # Template
.env                 # Local development (gitignored)
.env.test           # Test environment
.env.staging        # Staging environment
.env.production     # Production environment

Troubleshooting Development Issues

Port Already in Use

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

Database Connection Issues

# Check PostgreSQL status
pg-isready -h localhost -p 5432

# Reset database
npm run db:reset

Node Modules Issues

# Clear cache and reinstall
rm -rf node-modules package-lock.json
npm cache clean --force
npm install

Build Issues

# Clean build artifacts
npm run clean

# Rebuild
npm run build

Next Steps

Review Project Structure
Understand Architecture
Learn about Adding Features
Set up Testing
Read Contributing Guidelines

Development Resources

API Documentation: http://localhost:9090/docs
Storybook (UI components): http://localhost:6006
GraphQL Playground: http://localhost:9090/graphql
Internal Wiki: [Link to wiki]

Getting Help

Slack/Discord: #visionflow-dev
Team Meetings: Weekly on [day/time]
Pair Programming: Schedule via [calendar link]
Documentation: https://docs.visionflow.dev

Navigation: | 💻 Developer Guide | 🏗️ Architecture | 🧪 Testing

FilesExpand file tree

01-development-setup.md

Latest commit

History