How aipotheosis-labs/aci works
Project type and purpose
• This is a full-stack, multi-tenant AI-infra platform (“ACI.dev”) comprising:
• A React/Next.js frontend (“Dev Portal”)
• A FastAPI-based Python backend (Unified MCP server)
• A PostgreSQL database
• A CDK-driven AWS deployment layer
• 600+ external service connectors (apps/functions)
File structure
• Top-level “frontend” folder: Next.js v13 app, Typescript, UI components, API-calling library
• Top-level “backend”: Python FastAPI monolith with Alembic migrations, CLI, routes, function executors, middleware, multi-tenant auth, rate-limit/quota, Sentry integration
• “apps” and “backend/apps”: JSON definitions for built-in integrations (app.json + functions.json)
• “backend/deployment”: AWS CDK stack provisioning VPC, ECS/EKS (or Lambda), RDS, KMS, IAM policies
• CI/CD: GitHub workflows under .github/workflows
Key insights from README
• Purpose: expose 600+ tool integrations as unified function calls (MCP server) or via a lightweight Python SDK
• Multi-tenant authentication, dynamic discovery, natural-language permission boundaries
• Two primary access surfaces: Dev Portal (web UI) and Python SDK
Main components & interactions (to include
A. Client Layer
1. Web Portal (Next.js)
– Hosts project settings, usage dashboards, interactive Playground
– Calls backend REST endpoints (HTTPS)
2. Python SDK
– Provides direct function-call API to same backend endpoints
B. API Layer / Unified MCP Server (FastAPI)
– Authentication & OAuth2 proxy
– Rate limiting & quota enforcement
– Route handlers for apps, functions, projects, analytics, linked-accounts, webhooks
– Function executor subsystem (base, REST, OAuth2, connector)
– CLI commands (create_agent, upsert_app, etc.)
C. Persistence & State
– PostgreSQL (SQLAlchemy + Alembic)
– KMS for encryption (secrets, API keys)
D. External Services
– 600+ third-party APIs via “app_connectors” (Gmail, Slack, Google Calendar, etc.)
E. Deployment / Infrastructure
– AWS VPC, ECS/EKS or Lambda, RDS, KMS, IAM (deployed via CDK)
– CI/CD pipelines (GitHub Actions)
Relationships and data flows
• Browser/SDK → HTTPS → API Gateway/Load Balancer → FastAPI server
• FastAPI → SQL → PostgreSQL
• FastAPI → KMS → encrypted secrets
• FastAPI → External connectors → Third-party APIs
• CI/CD → Container registry → AWS (ECS/EKS) → running services
Architectural patterns & design principles
• Plugin-style connector architecture: “app_connectors” directory for extensibility
• Layered architecture: Presentation (frontend), API (backend routes & executors), Data (DB & secrets)
• Multi-tenant isolation: per-project scoping in database and auth middleware
• Infrastructure as code: AWS CDK for repeatable provisioning
• Observability: Sentry integration for error tracking; GitHub Actions for CI
Essential details without excessive clutter
• 600+ connectors under a single “App Connectors” sub-component, with a note “600+ JSON-driven integrations”
• Both access methods (Web Portal and SDK) converging on the same API