OrbitAgents

AI-powered web search and information agents platform

Table of Contents

• Overview
• Architecture
• Getting Started
• Prerequisites
• Quick Setup
• Development
• Services
• Infrastructure
• Contributing
• License

Overview

OrbitAgents is a modern, cloud-native platform for AI-powered web search and information retrieval. Built with a microservices architecture, it provides intelligent agents that can crawl, analyze, rank, and deliver relevant information to users.

🆓 100% FREE TIER AVAILABLE

Run the entire OrbitAgents platform using only free and open-source tools:

git clone https://github.com/your-org/OrbitAgents
cd OrbitAgents
make quick-start

Free Stack Includes:

• 🗄️ PostgreSQL (free database)
• 🔍 OpenSearch (free Elasticsearch alternative)
• 📦 MinIO (free S3-compatible storage)
• 🤖 Ollama (free local AI models)
• 🌐 Playwright (free browser automation)
• 📊 Prometheus + Grafana (free monitoring)
• 🔄 Redis (free message queue)
• 🚀 GitHub Actions (free CI/CD)

Key Features

• 🤖 AI-Powered Search: Intelligent information retrieval and ranking
• 🌐 Browser Automation: Visual automation builder with Playwright
• 🏗️ Microservices Architecture: Scalable and maintainable service design
• ☁️ Cloud Native: Built for AWS with Kubernetes orchestration
• 🔒 Secure: Authentication, authorization, and data protection
• 📊 Observable: Comprehensive monitoring and logging
• 🚀 CI/CD Ready: Automated testing, building, and deployment
• 💰 Cost Optimized: Free tier uses only open-source tools

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Frontend     │    │   API Gateway   │    │   Load Balancer │
│   (React/TS)    │◄──►│                 │◄──►│      (ALB)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                ┌───────────────┼───────────────┐
                │               │               │
        ┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
        │ Auth Service │ │Query Service│ │   Notify   │
        │   (FastAPI)  │ │  (FastAPI)  │ │  Service   │
        └──────────────┘ └─────────────┘ └────────────┘
                │               │               │
        ┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
        │   Crawler    │ │   Ranker    │ │ PostgreSQL │
        │   Service    │ │   Service   │ │    (RDS)   │
        │   (FastAPI)  │ │  (FastAPI)  │ │            │
        └──────────────┘ └─────────────┘ └────────────┘

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• AWS CLI (v2.0+) - Installation Guide
• Terraform (v1.6+) - Installation Guide
• kubectl (v1.28+) - Installation Guide
• Docker (v24.0+) - Installation Guide
• Node.js (v18+) - Installation Guide
• Python (v3.11+) - Installation Guide

Quick Setup

1. Clone the repository

   git clone https://github.com/your-org/OrbitAgents.git
   cd OrbitAgents

2. Configure AWS credentials

   aws configure

3. Initialize and apply infrastructure

   make infra-plan    # Review planned changes
   make infra-apply   # Apply infrastructure

4. Configure kubectl for EKS

   aws eks update-kubeconfig --region us-west-2 --name orbit-agents-cluster

5. Install development dependencies

   make install-deps

6. Start development environment

   # Terminal 1: Start frontend
   cd frontend/
   npm run dev
   
   # Terminal 2: Start auth service
   cd services/auth/
   python -m uvicorn main:app --reload --port 8001
   
   # Terminal 3: Start query service
   cd services/query/
   python -m uvicorn main:app --reload --port 8002

Development

Available Commands

make help           # Show all available commands
make lint           # Run all linters
make fmt            # Format all code
make test           # Run all tests
make build-all      # Build all Docker images
make infra-plan     # Plan Terraform changes
make infra-apply    # Apply Terraform changes

Code Style

• Python: Black, isort, flake8
• TypeScript: ESLint, Prettier
• Terraform: terraform fmt, tflint

Testing

# Run all tests
make test

# Run specific service tests
cd services/auth/
python -m pytest

# Run frontend tests
cd frontend/
npm run test

Services

Authentication Service (services/auth/)

• User registration and login
• JWT token management
• Password hashing and validation
• Port: 8000

Query Service (services/query/)

• Search query processing
• Result aggregation
• User preference handling
• Port: 8000

Crawler Service (services/crawler/)

• Web content crawling
• Content extraction and parsing
• Crawl scheduling and management
• Port: 8000

Ranker Service (services/ranker/)

• Search result ranking
• AI-powered relevance scoring
• Personalization algorithms
• Port: 8000

Notification Service (services/notify/)

• Email notifications
• Real-time alerts
• Notification preferences
• Port: 8000

Infrastructure

AWS Resources

• VPC: Custom VPC with public/private subnets
• EKS: Kubernetes cluster for container orchestration
• RDS: PostgreSQL database for persistent storage
• ECR: Container registry for Docker images
• ALB: Application load balancer for traffic distribution
• Route53: DNS management
• CloudWatch: Monitoring and logging

Terraform Modules

cd infra/
terraform plan    # Review changes
terraform apply   # Apply changes
terraform destroy # Clean up resources

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with ❤️ by the OrbitAgents Team