QUICKSTART.md

# SAAP Quick Start Guide

**satware Autonomous Agent Platform (SAAP)** - Local multi-agent orchestration platform

## ⚠️ CRITICAL SECURITY NOTICE

**Before running the project, you MUST remediate hardcoded API keys!**

The imported codebase contains **40+ hardcoded API keys** that must be replaced with environment variables before:
- Running the application
- Pushing to GitHub
- Deploying to any environment

**📋 Action Required:** See `SECURITY_REMEDIATION_REQUIRED.md` for detailed remediation steps.

---

## Prerequisites

### Required Software

1. **Python 3.10 or higher**
   ```bash
   python3 --version  # Should be 3.10+
   ```

2. **Node.js 18 or higher**
   ```bash
   node --version  # Should be v18+
   npm --version
   ```

3. **PostgreSQL Database**
   ```bash
   psql --version
   ```
   - Installation: https://www.postgresql.org/download/

4. **Git** (for version control)
   ```bash
   git --version
   ```

### Optional (Recommended)

- **Redis** (for caching and message queuing)
- **Docker** (for containerized deployment)
- **Docker Compose** (for multi-service orchestration)

---

## Installation Steps

### 1. Clone the Repository

```bash
git clone https://github.com/satwareAG/saap.git
cd saap
```

### 2. Backend Setup

#### 2.1 Create Python Virtual Environment

```bash
# Create virtual environment
python3 -m venv .venv

# Activate it
source .venv/bin/activate  # On Linux/macOS
# OR
.venv\Scripts\activate  # On Windows
```

#### 2.2 Install Python Dependencies

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

#### 2.3 Configure Environment Variables

```bash
# Copy the example environment file
cp backend/.env.example backend/.env

# Edit the .env file with your settings
nano backend/.env  # or use your preferred editor
```

**Required Configuration:**

```env
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/saap_db

# AI Provider API Keys (⚠️ SECURITY: Never commit these!)
OPENROUTER_API_KEY=your_openrouter_api_key_here
COLOSSUS_API_KEY=your_colossus_api_key_here

# Application Settings
DEBUG=True
LOG_LEVEL=INFO
```

#### 2.4 Set Up Database

```bash
# Create PostgreSQL database
createdb saap_db

# Run migrations (if applicable)
cd backend
alembic upgrade head
cd ..
```

### 3. Frontend Setup

#### 3.1 Install Node.js Dependencies

```bash
cd frontend
npm install
cd ..
```

---

## Starting the Application

### Option 1: Using Startup Scripts (Recommended)

#### Start Backend
```bash
./start_backend.sh
```

The backend will be available at:
- **API:** http://localhost:8000
- **API Docs (Swagger):** http://localhost:8000/docs
- **API Docs (ReDoc):** http://localhost:8000/redoc

#### Start Frontend (in a new terminal)
```bash
./start_frontend.sh
```

The frontend will be available at:
- **Application:** http://localhost:5173

### Option 2: Manual Start

#### Start Backend Manually
```bash
# Activate virtual environment
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate  # Windows

# Load environment variables
export $(cat backend/.env | grep -v '^#' | xargs)

# Start server
cd backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

#### Start Frontend Manually
```bash
cd frontend
npm run dev
```

---

## Verifying the Installation

### 1. Check Backend Health

```bash
curl http://localhost:8000/health
# Expected: {"status": "healthy"}
```

### 2. Access API Documentation

Open in browser: http://localhost:8000/docs

### 3. Access Frontend Application

Open in browser: http://localhost:5173

---

## Project Structure

```
saap/
├── backend/                    # Python FastAPI Backend
│   ├── agents/                 # AI Agent implementations
│   │   ├── colossus_agent.py   # Colossus (local) agent
│   │   └── openrouter_agent*.py # OpenRouter agents
│   ├── api/                    # API endpoints
│   ├── database/               # Database models & services
│   ├── services/               # Business logic services
│   ├── .env.example            # Environment template
│   └── main.py                 # FastAPI application entry
│
├── frontend/                   # Vue.js 3 Frontend
│   ├── src/
│   │   ├── components/         # Vue components
│   │   ├── views/              # Page views
│   │   ├── stores/             # Pinia state management
│   │   └── services/           # API client services
│   ├── package.json
│   └── vite.config.js          # Vite configuration
│
├── start_backend.sh            # Backend startup script
├── start_frontend.sh           # Frontend startup script
├── requirements.txt            # Python dependencies
└── README.md                   # Full documentation
```

---

## Common Issues & Troubleshooting

### Issue: `ModuleNotFoundError` when starting backend

**Solution:** Ensure virtual environment is activated and dependencies installed:
```bash
source .venv/bin/activate
pip install -r requirements.txt
```

### Issue: Port already in use (8000 or 5173)

**Solution:** Kill the process using the port:
```bash
# Find process using port 8000
lsof -i :8000  # or: netstat -tulpn | grep 8000

# Kill the process
kill -9 <PID>
```

### Issue: Database connection errors

**Solution:** 
1. Verify PostgreSQL is running: `systemctl status postgresql`
2. Check DATABASE_URL in `backend/.env`
3. Ensure database exists: `createdb saap_db`

### Issue: Frontend shows "Network Error"

**Solution:** 
1. Verify backend is running on port 8000
2. Check CORS settings in `backend/main.py`
3. Check browser console for specific errors

### Issue: Hardcoded API keys detected

**Solution:** 
1. **DO NOT push to GitHub yet!**
2. Follow `SECURITY_REMEDIATION_REQUIRED.md`
3. Replace all hardcoded keys with environment variables
4. Re-scan with Gitleaks: `gitleaks detect --no-git`

---

## Development Workflow

### Running Tests

**Backend Tests:**
```bash
cd backend
pytest
```

**Frontend Tests:**
```bash
cd frontend
npm test
```

### Code Quality Checks

**Backend (Python):**
```bash
# Linting
ruff check .

# Type checking
mypy backend/
```

**Frontend (JavaScript/TypeScript):**
```bash
cd frontend
npm run lint
```

---

## Security Best Practices

### 🔒 Essential Security Rules

1. **Never commit API keys** to version control
2. **Always use environment variables** for sensitive data
3. **Run Gitleaks** before every commit:
   ```bash
   gitleaks detect --no-git
   ```
4. **Update dependencies regularly**:
   ```bash
   pip list --outdated  # Python
   npm outdated         # Node.js
   ```
5. **Use strong passwords** for database and services
6. **Enable HTTPS** in production environments

---

## Next Steps

After successful startup:

1. ✅ **Complete Security Remediation** (see `SECURITY_REMEDIATION_REQUIRED.md`)
2. ✅ **Configure all agents** in the dashboard
3. ✅ **Test agent orchestration** with sample tasks
4. ✅ **Review API documentation** at http://localhost:8000/docs
5. ✅ **Set up development database** with test data
6. ✅ **Configure Redis/RabbitMQ** (optional, for advanced features)

---

## Additional Resources

- **Full Documentation:** `README.md`
- **Security Remediation:** `SECURITY_REMEDIATION_REQUIRED.md`
- **Import Notes:** `IMPORT_NOTES.md`
- **API Documentation:** http://localhost:8000/docs (when running)
- **Project Repository:** https://github.com/satwareAG/saap

---

## Support & Contact

- **Student:** Hanan Wandji Danga
- **Organization:** satware AG
- **Project:** Master's Thesis - SAAP Platform
- **Timeline:** 2025-09-15 to 2026-03-14

For issues or questions, please create an issue on the GitHub repository.

---

**Last Updated:** 2025-11-11