Local Development Setup Guide

Complete guide to setting up ATOM SaaS development environment on your local machine.

Prerequisites

Required Software

Development Environment:

• Node.js: Version 20.x or higher (Download)
• Python: Version 3.11 or higher (Download)
• Docker Desktop: Latest version (Download)
• Git: Latest version (Download)

Optional but Recommended:

• PostgreSQL Client: pgAdmin, DBeaver, or psql
• Redis CLI: For cache inspection
• VS Code: Recommended IDE with extensions

VS Code Extensions:

• ESLint
• Prettier
• Python
• PostgreSQL
• Docker

Quick Start

1. Clone Repository

# Clone the repository
git clone https://github.com/your-org/atom-saas.git
cd atom-saas

# Verify you're on main branch
git branch

2. Install Dependencies

# Frontend dependencies (Node.js)
npm install

# Backend dependencies (Python)
cd backend-saas
python -m venv venv

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

# Install Python packages
pip install -r requirements.txt

cd ..

3. Environment Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# Required variables:
# - DATABASE_URL
# - REDIS_URL
# - JWT_SECRET
# - OPENAI_API_KEY (optional, for BYOK testing)

4. Start Services

# Terminal 1: Start PostgreSQL with Docker
docker-compose up -d postgres redis

# Terminal 2: Start backend
cd backend-saas
source venv/bin/activate
uvicorn core.main:app --reload --port 8000

# Terminal 3: Start frontend
npm run dev

5. Access Applications

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Database: localhost:5432

Detailed Setup

Database Setup

PostgreSQL

Option 1: Docker (Recommended)

# Start PostgreSQL container
docker run --name atom-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=atom_saas_local \
  -p 5432:5432 \
  -d postgres:15

# Verify connection
docker exec -it atom-postgres psql -U postgres -d atom_saas_local

Option 2: Local Installation

# macOS (Homebrew)
brew install postgresql@15
brew services start postgresql@15

# Create database
createdb atom_saas_local

Run Migrations

cd backend-saas

# Run all migrations
alembic upgrade head

# Verify migration status
alembic current

# (Optional) Seed sample data
python scripts/seed_sample_data.py

Redis Setup

Option 1: Docker (Recommended)

# Start Redis container
docker run --name atom-redis \
  -p 6379:6379 \
  -d redis:7-alpine

# Test connection
docker exec -it atom-redis redis-cli ping
# Should return: PONG

Option 2: Local Installation

# macOS (Homebrew)
brew install redis
brew services start redis

# Test connection
redis-cli ping

Backend Setup

Virtual Environment

cd backend-saas

# Create virtual environment
python3.11 -m venv venv

# Activate environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

Configuration

Create backend-saas/.env:

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/atom_saas_local

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT
JWT_SECRET=your-secret-key-here

# API Keys (for testing)
OPENAI_API_KEY=sk-test-key-here
ANTHROPIC_API_KEY=sk-ant-test-key-here

# Environment
ENVIRONMENT=development
DEBUG=true

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

Run Backend Server

cd backend-saas
source venv/bin/activate

# Development server with auto-reload
uvicorn core.main:app --reload --port 8000 --host 0.0.0.0

# With additional debugging
uvicorn core.main:app --reload --log-level debug

Verify Backend:

• API: http://localhost:8000
• Health Check: http://localhost:8000/api/health
• Swagger Docs: http://localhost:8000/docs

Frontend Setup

Install Dependencies

# From project root
npm install

# Verify installation
npm list --depth=0

Configuration

Create .env.local:

# Next.js
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Environment
NEXT_PUBLIC_ENVIRONMENT=development

# Feature flags
NEXT_PUBLIC_ENABLE_ANALYTICS=false

Run Development Server

# Start Next.js dev server
npm run dev

# Or with specific port
npm run dev -- -p 3000

Verify Frontend:

• App: http://localhost:3000
• API Routes: http://localhost:3000/api/*

Development Workflow

Running Tests

Frontend Tests:

# Run all tests
npm test

# Run in watch mode
npm test -- --watch

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test path/to/test.spec.ts

Backend Tests:

cd backend-saas
source venv/bin/activate

# Run all tests
pytest

# Run with coverage
pytest --cov=core --cov-report=html

# Run specific test file
pytest tests/test_specific.py

# Run with verbose output
pytest -v

E2E Tests:

# Run all E2E tests
npm run test:e2e

# Run specific E2E test
npx playwright test path/to/test.spec.ts

# Run with UI
npx playwright test --ui

Database Migrations

cd backend-saas

# Create new migration
alembic revision --autogenerate -m "description"

# Upgrade to latest
alembic upgrade head

# Downgrade one step
alembic downgrade -1

# View migration history
alembic history

# Reset database (development only!)
alembic downgrade base
alembic upgrade head

Code Quality

Linting:

# Frontend - Check linting
npm run lint

# Frontend - Fix linting issues
npm run lint:fix

# Backend - Check linting
cd backend-saas
flake8 core/
black --check core/

Formatting:

# Frontend - Format code
npm run format

# Backend - Format code
cd backend-saas
black core/
isort core/

Debugging

Frontend Debugging:

1. Open Chrome DevTools (F12)
2. Go to "Sources" tab
3. Set breakpoints in TypeScript files
4. Use React DevTools for component inspection

Backend Debugging:

# Run with debugger
cd backend-saas
python -m pdb -m uvicorn core.main:app --reload

# Or use VS Code debugger
# Create .vscode/launch.json:
{
  "name": "Python: FastAPI",
  "type": "python",
  "request": "launch",
  "module": "uvicorn",
  "args": ["core.main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
  "envFile": "${workspaceFolder}/backend-saas/.env",
  "cwd": "${workspaceFolder}/backend-saas"
}

Common Issues & Solutions

Issue: Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
npm run dev -- -p 3001

Issue: Database Connection Failed

Problem: connection refused or could not connect to server

Solution:

# Verify PostgreSQL is running
docker ps | grep postgres

# Check connection
psql -U postgres -h localhost -d atom_saas_local

# Restart PostgreSQL
docker restart atom-postgres

Issue: Module Not Found

Problem: ModuleNotFoundError: No module named 'xxx'

Solution:

cd backend-saas

# Ensure virtual environment is activated
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

# Clear Python cache
find . -type d -name __pycache__ -exec rm -r {} +

Issue: CORS Errors

Problem: API requests blocked by CORS policy

Solution: Check backend CORS configuration in core/main.py:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Issue: Migrations Fail

Problem: alembic.util.exc.CommandError: Target database is not up to date

Solution:

cd backend-saas

# Check current version
alembic current

# View migration history
alembic history

# Stamp to latest version (use carefully!)
alembic stamp head

# Or reset and reapply
alembic downgrade base
alembic upgrade head

IDE Configuration

VS Code Settings

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "./backend-saas/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true
  }
}

VS Code Extensions

Recommended extensions for ATOM SaaS development:

1. Python - Python language support
2. Pylance - Python IntelliSense
3. ESLint - JavaScript/TypeScript linting
4. Prettier - Code formatting
5. PostgreSQL - Database management
6. Docker - Container support
7. GitLens - Git supercharged
8. Thunder Client - API testing (alternative to Postman)

Development Tips

Hot Reload

• Frontend: Next.js automatically reloads on file changes
• Backend: Use --reload flag with uvicorn for auto-restart

Database Inspection

# Open PostgreSQL shell
docker exec -it atom-postgres psql -U postgres -d atom_saas_local

# Useful queries
\dt                    # List tables
\d table_name          # Describe table
SELECT * FROM agents;  # Query data

Redis Inspection

# Open Redis CLI
docker exec -it atom-redis redis-cli

# Useful commands
KEYS *                 # List all keys
GET key               # Get value
FLUSHDB               # Clear all data (development only!)

Environment Variables

List all required environment variables:

Backend (.env):

• DATABASE_URL
• REDIS_URL
• JWT_SECRET
• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• S3_BUCKET

Frontend (.env.local):

• NEXT_PUBLIC_API_URL
• NEXT_PUBLIC_APP_URL
• NEXT_PUBLIC_ENVIRONMENT

Production Considerations

Before Deploying

1. Run Tests:

   npm test
   cd backend-saas && pytest
   npm run test:e2e

2. Check Linting:

   npm run lint
   cd backend-saas && flake8 core/

3. Build Frontend:

   npm run build

4. Database Migrations:

   cd backend-saas
   alembic upgrade head

Performance Optimization

1. Enable Production Mode:

   # Frontend
   NODE_ENV=production npm run build
   
   # Backend
   uvicorn core.main:app --workers 4

2. Configure CDN:

   • Set up CDN for static assets
   • Configure caching headers

3. Database Connection Pooling:

   • Configure PgBouncer
   • Tune pool sizes

Next Steps

After setting up local development:

1. Explore Documentation:

   • Architecture Overview
   • API Reference
   • Brain Systems

2. Learn Patterns:

   • Multi-Tenancy Patterns
   • Brain System Usage

3. Start Development:

   • Read Development Workflow
   • Review Testing Guide

Support

Getting Help

• Documentation: https://docs.atomagentos.com
• Issues: GitHub Issues
• Support: support@atomagentos.com

Troubleshooting

1. Check logs:

   # Backend logs
   cd backend-saas
   tail -f logs/app.log
   
   # Frontend logs
   # Check browser console

2. Clear caches:

   # Clear node modules
   rm -rf node_modules package-lock.json
   npm install
   
   # Clear Python cache
   find . -type d -name __pycache__ -exec rm -r {} +
   
   # Clear Docker containers
   docker system prune -a

3. Rebuild from scratch:

   # Database
   alembic downgrade base
   alembic upgrade head
   
   # Frontend
   rm -rf .next
   npm run dev

Last Updated: 2025-02-06 Documentation Version: 1.0.0 Platform Version: 8.0