> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt > Use this file to discover all available pages before exploring further. # Architecture Deep Dive > Understand Aurora's architecture, tech stack, and codebase structure ## Architecture Overview Aurora is built as a microservices architecture using Docker Compose. The system consists of multiple components that work together to provide a natural-language interface for cloud infrastructure management. ## System Components ### Backend Services #### Aurora Server (Flask API) * **Location**: `server/` * **Entry Point**: `main_compute.py` * **Port**: 5080 * **Framework**: Flask 3.1.3 * **Purpose**: REST API for all compute operations, user management, and cloud provider integrations #### Chatbot WebSocket Server * **Location**: `server/` * **Entry Point**: `main_chatbot.py` * **Port**: 5006 * **Protocol**: WebSocket * **Purpose**: Real-time conversational AI interface powered by LangGraph #### Celery Worker * **Location**: `server/` * **Purpose**: Background task processing for long-running operations * **Broker**: Redis * **Tasks**: Cloud resource discovery, billing updates, infrastructure provisioning #### Celery Beat * **Purpose**: Periodic task scheduler * **Tasks**: Scheduled billing updates, resource synchronization ### Frontend * **Location**: `client/` * **Framework**: Next.js 15 * **Language**: TypeScript * **UI Components**: shadcn/ui (Radix UI primitives) * **Styling**: Tailwind CSS * **Authentication**: Auth.js (NextAuth v5 beta) * **Port**: 3000 ### Data Layer #### PostgreSQL * **Port**: 5432 * **Database**: `aurora_db` * **Purpose**: Primary relational database for users, projects, infrastructure state * **Driver**: psycopg2 (backend) #### Weaviate * **Port**: 8080 * **Purpose**: Vector database for semantic search and RAG (Retrieval-Augmented Generation) * **Use Cases**: Knowledge base search, context retrieval for AI agent #### Redis * **Port**: 6379 * **Purpose**: Message broker for Celery, caching layer ### Infrastructure Services #### HashiCorp Vault * **Port**: 8200 * **Purpose**: Secrets management for cloud provider credentials, API keys * **Storage**: File-based with Docker volumes (`vault-data`, `vault-init`) * **Mount**: KV v2 engine at `aurora` mount * **Auto-initialization**: `vault-init` container handles setup and unsealing #### SeaweedFS * **S3 API Port**: 8333 * **File Browser**: 8888 * **Cluster Status**: 9333 * **Purpose**: S3-compatible object storage for Terraform state files, artifacts * **License**: Apache 2.0 * **Alternatives**: AWS S3, Cloudflare R2, MinIO, GCS (S3 interop) ## Tech Stack ### Backend Technologies ```python theme={null} # Core Framework Flask==3.1.3 Flask-Cors==6.0.0 flask-jwt-extended>=4.4.4 # AI/ML Stack langchain==1.2.6 langchain_community==0.3.31 langchain_core==1.2.11 langchain_openai==1.1.7 langchain-anthropic>=0.3.0 langchain-google-genai>=2.0.0 langgraph==1.0.6 # LLM Providers openai>=1.109.1,<3.0.0 anthropic>=0.18.0 # Cloud Providers boto3==1.36.26 # AWS google-cloud-* # GCP azure-identity==1.16.1 # Azure azure-mgmt-resource==23.0.1 ovh==1.1.0 # OVH Cloud # Background Tasks celery==5.3.6 redis==5.0.1 # Database psycopg2-binary weaviate_client>=4.15.0 # Secrets Management hvac>=2.1.0 # Vault client # Infrastructure as Code kubernetes==26.1.0 paramiko>=3.4.0 # SSH # Web Server gunicorn==23.0.0 gevent==25.9.1 ``` ### Frontend Technologies ```json theme={null} { "framework": "next@^15.5.12", "react": "^18.2.0", "typescript": "5.7.2", "ui-components": [ "@radix-ui/react-*", "shadcn/ui", "lucide-react" ], "styling": [ "tailwindcss@^3.4.1", "tailwindcss-animate", "class-variance-authority" ], "authentication": "next-auth@^5.0.0-beta.30", "visualization": [ "recharts@^2.15.0", "@xyflow/react@^12.10.0" ], "code-editor": "@monaco-editor/react@^4.7.0" } ``` ## Project Structure ### Backend Structure (`server/`) ``` server/ ├── main_compute.py # Flask API entry point ├── main_chatbot.py # WebSocket chatbot entry point ├── celery_config.py # Celery task configuration ├── requirements.txt # Python dependencies │ ├── routes/ # Flask blueprints (API endpoints) │ ├── aws/ # AWS-specific routes │ ├── azure/ # Azure-specific routes │ ├── gcp/ # GCP-specific routes │ ├── github/ # GitHub integration │ ├── slack/ # Slack integration │ ├── terraform/ # Terraform operations │ └── ... │ ├── chat/ # AI chatbot implementation │ └── backend/ │ └── agent/ │ ├── agent.py # Main agent logic │ ├── workflow.py # LangGraph workflow │ ├── llm.py # LLM configuration │ ├── tools/ # Agent tools │ ├── prompt/ # Prompt templates │ └── providers/ # LLM provider implementations │ ├── connectors/ # Cloud provider connectors │ ├── aws_connector/ │ ├── azure_connector/ │ ├── gcp_connector/ │ ├── github_connector/ │ ├── slack_connector/ │ └── ... │ ├── utils/ # Utility modules │ ├── auth/ # Authentication utilities │ ├── db/ # Database utilities │ ├── secrets/ # Vault integration │ ├── storage/ # S3-compatible storage │ ├── terraform/ # Terraform helpers │ ├── kubectl/ # Kubernetes utilities │ └── billing/ # Cost tracking │ ├── services/ # Business logic services │ ├── discovery/ # Resource discovery │ ├── correlation/ # Resource correlation │ └── graph/ # Graph database operations │ └── tests/ # Test suite ``` ### Frontend Structure (`client/`) ``` client/ ├── src/ │ ├── app/ # Next.js 15 App Router │ │ ├── api/ # API routes (Next.js API) │ │ │ ├── auth/ # Authentication endpoints │ │ │ ├── aws-*/ # AWS proxy endpoints │ │ │ ├── azure-*/ # Azure proxy endpoints │ │ │ └── gcp-*/ # GCP proxy endpoints │ │ ├── (dashboard)/ # Dashboard layouts │ │ ├── chat/ # Chat interface │ │ └── layout.tsx # Root layout │ │ │ ├── components/ # React components │ │ ├── ui/ # shadcn/ui components │ │ ├── chat/ # Chat-specific components │ │ ├── dashboard/ # Dashboard widgets │ │ └── providers/ # Cloud provider components │ │ │ ├── lib/ # Utility libraries │ │ ├── auth.ts # Auth.js configuration │ │ └── utils.ts # Helper functions │ │ │ └── types/ # TypeScript type definitions │ ├── public/ # Static assets ├── next.config.ts # Next.js configuration ├── tailwind.config.ts # Tailwind CSS configuration └── tsconfig.json # TypeScript configuration ``` ## Data Flow ### Chat Workflow 1. **User Input**: User sends message via WebSocket from frontend 2. **WebSocket Server**: `main_chatbot.py` receives message 3. **LangGraph Agent**: Message flows through LangGraph workflow 4. **Tool Execution**: Agent calls cloud provider tools, database queries 5. **LLM Processing**: OpenRouter/Anthropic/OpenAI generates response 6. **Streaming Response**: Response streamed back to frontend via WebSocket ### Infrastructure Provisioning 1. **User Request**: User requests infrastructure via chat or UI 2. **Agent Analysis**: LangGraph agent analyzes requirements 3. **Terraform Generation**: Agent generates Terraform configurations 4. **State Storage**: Terraform state stored in SeaweedFS 5. **Approval Flow**: User confirms changes via WebSocket 6. **Celery Task**: Background task executes Terraform apply 7. **Result Notification**: User notified of completion ### Authentication Flow 1. **Login**: User submits credentials to Next.js API route 2. **Auth.js**: NextAuth validates credentials against PostgreSQL 3. **JWT Token**: Stateless JWT token issued (flask-jwt-extended) 4. **Session**: Session stored in secure HTTP-only cookie 5. **API Requests**: JWT included in Authorization header 6. **Validation**: Flask middleware validates JWT on each request ## Agent Architecture (LangGraph) Aurora uses LangGraph for orchestrating the AI agent workflow: ```python theme={null} # Simplified workflow structure from langgraph.graph import StateGraph workflow = StateGraph(State) # Nodes workflow.add_node("agent", agent_node) workflow.add_node("tools", tool_execution_node) workflow.add_node("human_approval", approval_node) # Edges workflow.add_edge("agent", "tools") workflow.add_conditional_edges( "tools", should_continue, { "continue": "agent", "approval_required": "human_approval", "end": END } ) ``` ### Agent State ```python theme={null} class State(TypedDict): messages: List[BaseMessage] # Conversation history user_id: str # Current user session_id: str # Chat session ID cloud_context: Dict # Active cloud connections pending_approval: Optional[Dict] # Infrastructure changes awaiting approval ``` ### Agent Tools The agent has access to various tools: * **Cloud Provider Tools**: List resources, create/modify/delete resources * **Database Tools**: Query infrastructure state, user data * **Terraform Tools**: Generate, validate, apply IaC * **Knowledge Base Tools**: Search documentation, retrieve context * **Billing Tools**: Get cost estimates, analyze spending ## Secrets Management Aurora uses HashiCorp Vault for secure secrets storage: ### Secret References Secrets stored in the database use a special format: ```python theme={null} # Example: Cloud provider token in database user_credential = "vault:kv/data/aurora/users/aws-token-user123" # At runtime, resolved via Vault API from utils.secrets.vault_client import get_secret actual_token = get_secret(user_credential) ``` ### Vault Structure ``` aurorount)/ └── users/ ├── aws-token-{user_id} ├── gcp-sa-{user_id} ├── azure-token-{user_id} └── ... ``` ## Storage Architecture Aurora uses S3-compatible storage via SeaweedFS: ```python theme={null} from utils.storage.storage import get_storage_manager storage = get_storage_manager() # Upload Terraform state storage.upload_file( bucket="terraform-state", key=f"projects/{project_id}/terraform.tfstate", file_path="/tmp/terraform.tfstate" ) # Download state storage.download_file( bucket="terraform-state", key=f"projects/{project_id}/terraform.tfstate", destination="/tmp/terraform.tfstate" ) ``` ## Code Style Guidelines ### Python (Backend) * **Naming**: `snake_case` for functions, variables, files * **Imports**: Group imports (stdlib, third-party, local) * **Error Handling**: Use try/except with logging * **Async**: Use async/await with langchain/langgraph * **Logging**: Use `logging.INFO` level, no emojis in logs * **Database**: Use connection pooling via `db_pool` * **Routes**: Organize as Flask blueprints in `routes/` ### TypeScript (Frontend) * **Naming**: `camelCase` for variables/functions, `PascalCase` for components * **Imports**: Use path alias `@/*` for `./src/*` * **Components**: Functional components with TypeScript * **Hooks**: Follow React hooks best practices * **Error Handling**: Use try/catch with user-friendly messages * **Styling**: Use Tailwind CSS utility classes * **URLs**: Use `kebab-case` for routes ### General * Keep functions small and focused * Avoid deep nesting * Write self-documenting code * Add comments for complex logic only * No commented-out code in commits * No emojis in code or logs ## Configuration ### Docker Compose Files * **docker-compose.yaml**: Development environment * **docker-compose.prod-local.yml**: Production builds for local testing **Important**: Always update both files together to keep environment variables in sync. ### Environment Variables Configuration is managed via `.env` file. See `.env.example` for all available options. Key configuration areas: * Database credentials * LLM API keys * Cloud provider credentials (or use Vault) * Service URLs and ports * Feature flags ## Next Steps Set up your development environment Learn how to contribute to Aurora Write and run tests