ATOM Documentation

← Back to App

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:**
  1. **Check Linting:**
  1. **Build Frontend:**
  1. **Database Migrations:**

Performance Optimization

  1. **Enable Production Mode:**

# Backend

uvicorn core.main:app --workers 4

```

  1. **Configure CDN:**
  • Set up CDN for static assets
  • Configure caching headers
  1. **Database Connection Pooling:**
  • Configure PgBouncer
  • Tune pool sizes

---

Next Steps

After setting up local development:

  1. **Explore Documentation:**
  1. **Learn Patterns:**
  1. **Start Development:**

---

Support

Getting Help

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

Troubleshooting

  1. Check logs:

# Frontend logs

# Check browser console

```

  1. Clear caches:

# Clear Python cache

find . -type d -name __pycache__ -exec rm -r {} +

# Clear Docker containers

docker system prune -a

```

  1. Rebuild from scratch:

# Frontend

rm -rf .next

npm run dev

```

---

**Last Updated:** 2025-02-06

**Documentation Version:** 1.0.0

**Platform Version:** 8.0