System Architecture

CloudAEye self hosted Code Review supports AWS ECS only. The Terraform bundle deploys CloudAEye on ECS Managed Instances in a customer AWS account, with public access through an Application Load Balancer and all application, worker, and data services running privately inside the VPC.

Service Flow Diagram

AWS ECS Deployment

Layer	AWS resources	Purpose
Entry point	Application Load Balancer	Public HTTP listener and path-based routing for CloudAEye UI, APIs, SSO, and GitHub webhooks
Runtime	ECS cluster with ECS Managed Instances	Runs CloudAEye application containers, workers, MongoDB, ChromaDB
Network	VPC, public subnet, private subnet, internet gateway, NAT gateway	Keeps ECS tasks private while allowing public ALB ingress
Service discovery	AWS Cloud Map private DNS	Provides internal names for mongodb.cloudaeye.local and chromadb.cloudaeye.local
Queue	Amazon SQS	Separate cloudaeye-indexing-queue and cloudaeye-review-queue for asynchronous work
Authentication	Amazon Cognito	Handles tenant login and SSO integration through the cloudaeye-auth service
Storage	EBS volumes	Persists MongoDB data and ChromaDB vector data
Observability	CloudWatch log groups and ECS Container Insights	Stores service logs and cluster/task metrics

Core Services

Service	Exposure	Function
cloudaeye-web	Public	Serves the CloudAEye web console
cloudaeye-auth	Public	Handles login, tenant registration, and Cognito-backed auth flows
cloudaeye-api	Public	Lists tenant repositories and supports UI API requests
cloudaeye-repositories	Public	Connects repositories and starts repository provisioning
cloudaeye-indexer-api	Public	Starts vectorization and sends indexing work to SQS
cloudaeye-webhook	Public	Receives GitHub webhook events and starts pull request review work
cloudaeye-reviews	Public	Orchestrates pull request reviews and review queue processing
cloudaeye-secrets	Public	Scans pull request changes for secrets during review processing

Background Workers

Worker	Runtime	Function
cloudaeye-indexer-worker	ECS background task	Consumes cloudaeye-indexing-queue, vectorizes repositories, and writes artifacts to ChromaDB and MongoDB
cloudaeye-reviews	ECS background task	Consumes cloudaeye-review-queue, reads artifacts from ChromaDB and MongoDB, calls the LLM provider, and stores review results in MongoDB

Infrastructure Services

Service	Function
MongoDB	Private ECS service with encrypted EBS storage for application data, tenant state, review results, and license status
ChromaDB	Private ECS service with encrypted EBS storage for vectorized code artifacts
Amazon SQS	Provides cloudaeye-indexing-queue for indexing work and cloudaeye-review-queue for review work
Amazon Cognito	Provides authentication and SSO-backed login for cloudaeye-auth
AWS Cloud Map	Provides private DNS names for MongoDB and ChromaDB inside the VPC
Application Load Balancer	Public entry point for the web console, APIs, SSO callbacks, and GitHub webhooks
CloudWatch	Stores ECS service logs and cluster/task metrics

Setup Flow

This flow covers login, repository selection, provisioning, and vectorization.

1. The user opens the CloudAEye UI through the public ALB.
2. The UI sends login and tenant requests to cloudaeye-auth.
3. cloudaeye-auth uses Cognito for authentication and SSO-backed login.
4. After login, the UI calls cloudaeye-api to list repositories available to the tenant.
5. The user selects a repository in the UI.
6. The UI calls cloudaeye-repositories for repository integration and infrastructure provisioning.
7. The integration service calls cloudaeye-indexer-api to start vectorization.
8. cloudaeye-indexer-api enqueues vectorization work in cloudaeye-indexing-queue.
9. cloudaeye-indexer-worker consumes indexing jobs, generates vector data, writes code context to ChromaDB, and records processing state in MongoDB.

Pull Request Review Flow

This flow covers GitHub webhook processing and review generation.

1. GitHub sends webhook events to the cloudaeye-webhook service.
2. cloudaeye-webhook forwards the pull request event to cloudaeye-reviews.
3. During review, the cloudaeye-reviews ECS service calls cloudaeye-secrets to scan the pull request changes for secrets.
4. cloudaeye-reviews sends asynchronous review work to cloudaeye-review-queue.
5. Review processing uses ChromaDB and MongoDB to retrieve repository context created during vectorization.
6. cloudaeye-reviews calls the configured LLM provider to generate review output.
7. Review state, review results, and related application data are persisted in MongoDB.

Networking And Security Boundaries

The ALB is the only public ingress path. Its security group allows inbound traffic on the configured application port from allowed_app_cidr.

All ECS tasks run in the private subnet with assignPublicIp disabled. Private tasks use the NAT gateway for outbound access to ECR, AWS APIs, source control providers, license validation, and configured LLM providers.

MongoDB and ChromaDB are reachable only from ECS tasks through the ECS service security group and Cloud Map private DNS. They are not registered behind the public ALB.

Runtime secrets and customer-specific values are supplied through Terraform variables and container environment variables. Protect terraform.tfvars and Terraform state because they contain sensitive values.

Storage

MongoDB and ChromaDB each run as a single ECS service with an encrypted EBS volume. MongoDB stores application data, tenant state, review results. ChromaDB stores vectorized code context used during review generation.