ATOM SaaS Documentation
**"The First AI Workforce You Can Actually Trust"**
Welcome to the comprehensive documentation for ATOM SaaS - a multi-tenant AI agent platform with cognitive architectures, learning engines, and enterprise-grade governance.
---
Quick Links
š Get Started Fast
- Quick Start Guide - Get started in 5 minutes
- Architecture Overview - System design and architecture
- API Reference - All API endpoints
- Development Setup - Local development environment
---
Documentation by Audience
š¤ For Users
**Getting Started**
- Quick Start Guide - Start using ATOM in 5 minutes
- Understanding Agents - What are agents and how do they work?
- Agent Maturity Levels - Student ā Intern ā Supervised ā Autonomous
**Agent Management**
- Creating Agents - Create and configure your AI agents
- Agent Maturity & Calibration - Understanding AI-guided graduation
- Self-Evolution (Alpha Evolver) - How agents improve their own code
- Intent Routing - CHAT vs WORKFLOW vs TASK modes
- Skills & Capabilities - Assign skills to your agents
**Integrations**
- Integration Overview - Available integrations
- OAuth Setup Guide - Connect third-party services
- Supported Integrations - 39+ native providers
**Canvas & Marketplace**
- Canvas Overview - Visual workspace for agent development
- Using the Marketplace - Browse and install components
- Publishing Components - Share your creations
**Desktop App**
- Desktop App Overview - Tauri desktop application
- Terminal Access - Safe terminal execution
- Docker Integration - Container management
---
š» For Developers
**Setup & Configuration**
- Local Development Setup - Complete environment setup
- Environment Variables - Configuration reference
- Database Setup - PostgreSQL, migrations, seeding
- Troubleshooting Setup - Common setup issues
**Development Standards**
- Code Style Guide - TypeScript and Python standards
- Multi-Tenancy Patterns - Critical tenant isolation patterns
- Brain System Usage - Proper brain system usage
- Security Best Practices - Security guidelines
- Testing Guide - Unit, integration, and E2E testing
- Git Workflow - Branching and contribution
**Architecture**
- Architecture Overview - High-level system design
- Brain Systems - Cognitive architecture details
- Cognitive Architecture
- Learning Engine
- World Model
- Reasoning Engine
- Cross-System Reasoning
- Episodic Memory & Graduation
- Graduation Exam System
- Episode Feedback (RLHF)
- Multi-Tenancy Architecture - Tenant isolation strategy
- Data Flow - Request/response flows
**API Reference**
- API Overview - All API endpoints
- Agent APIs - Agent management endpoints
- Graduation APIs - Graduation and episodic memory endpoints
- Marketplace APIs - Canvas-skill marketplace endpoints
- Integration APIs - Integration management endpoints
- Authentication - Auth methods and tokens
- Error Codes - Standard error responses
- Rate Limiting - Rate limit policies
š Tenant API Reference
- Authentication Guide - API keys and OAuth 2.0 setup
- **Interactive Docs:**
https://[your-tenant].atomagentos.com/api/docs - **Base API URL:**
https://[your-tenant].atomagentos.com/api/v1
**Development Workflows**
- Adding New Features - Feature development workflow
- Database Migrations - Alembic migration guide
- Creating Skills - Skill development
- Canvas Components - Component development
- Testing Strategies - Comprehensive testing approach
- Debugging - Debugging techniques
---
š§ For Administrators
**Deployment**
- Deployment Guide - Production deployment
- Cloud Deployment - Production infrastructure setup
- AWS Deployment - AWS infrastructure setup
- Docker Deployment - Container orchestration
- Database Migrations - Running migrations in production
**Operations**
- Monitoring - Application monitoring
- Logging - Log aggregation and analysis
- Performance Tuning - Optimization strategies
- Scaling - Horizontal and vertical scaling
- Backup & Recovery - Data protection
**Security & Governance**
- **Security Overview** ā Master guide to multi-layered defense.
- **Multi-Tenant Isolation** ā Technical RLS patterns.
- **Terminal Security** ā Command whitelisting and safety.
- **Package Management** ā Secure dependency installation.
- **Agent Governance** ā Maturity & intervention UI.
**Troubleshooting**
- Common Issues - Frequently encountered problems
- Database Issues - Database-specific issues
- Performance Issues - Slowdown diagnosis
- Integration Issues - Third-party service problems
---
š Key Concepts
Brain Systems
ATOM SaaS includes six cognitive brain systems that enable human-like intelligence:
- **Cognitive Architecture** - Reasoning, memory, attention, language processing
- **Learning Engine** - Experience-based learning and adaptation
- **World Model** - Long-term memory with semantic search
- **Reasoning Engine** - Proactive intelligence and interventions
- **Cross-System Reasoning** - Multi-system data correlation
- **Backend Intelligence** - Business logic and communication processing
ā ļø **Warning:** Brain systems are critical - changes affect all agent behavior. See Brain System Usage.
Multi-Tenancy
Every operation is scoped to a tenant using:
- Subdomain-based routing (
tenant.atomagentos.comor custom domains) - Row-Level Security (RLS) in PostgreSQL
- S3 prefix isolation (
s3://atom-saas/{tenant_id}/) - Redis namespace separation (
tenant:{tenant_id}:...)
š“ **Critical:** Always extract tenant context. Never skip tenant_id filtering. See Tenant Isolation Patterns.
Agent Maturity & Calibration
Agents progress through four maturity levels (Student, Intern, Supervised, Autonomous). The **Maturity Calibration Service** uses AI to analyze Episodic Memory and automatically promotes or demotes agents based on their zero-intervention ratio and success rate.
Capability Graduation
Agents can earn autonomy in specific domains via **Capability Graduation**. This allows an agent to be "Autonomous" in Marketing but remain as a "Student" in Financial operations until it proves competency in that specific sector.
Self-Evolution (Alpha Evolver)
The **Alpha Evolver** engine allows agents to autonomously improve their own code and tools. It generates mutations, tests them in **Secure Sandboxes**, and adopts the highest-performing variants.
BYOK (Bring Your Own Key)
Tenants provide their own LLM API keys stored in tenant_settings table. The platform automatically routes to tenant-provided keys for all AI operations.
---
šÆ Architecture Diagram
**See full architecture diagrams ā**
---
š Quick Start
For Users
- **Create Account** (2 min)
- **Create Agent** (2 min)
- **Run Task** (1 min)
š **Full Quick Start Guide ā**
For Developers
- **Clone Repository**
- **Install Dependencies**
# Backend (Python 3.11+)
cd backend-saas
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
- **Start Development Servers**
# Terminal 2: Backend
cd backend-saas
uvicorn core.main:app --reload # :8000
```
š **Full Development Setup ā**
---
š Documentation Index
Architecture
API Reference
- API Overview
- Agent APIs
- Graduation APIs
- Marketplace APIs
- Public Marketplace API - Browse and discover skills
Development
User Guides
Deployment
Operations
Troubleshooting
---
š¤ Contributing
Found a documentation issue? Please:
- Check for existing issues in GitHub
- Create a new issue with detailed description
- Submit a PR with your improvements
**Contribution Guidelines ā**
---
š Support
- **Documentation Issues:** GitHub Issues
- **Platform Support:** support@atomagentos.com
- **Developer Community:** [Discord/Slack]
---
**Last Updated:** 2025-02-06
**Documentation Version:** 1.0.0
**Platform Version:** 8.0 (Production Ready)