# aipotheosis-labs/aci architecture

> Architecture diagram of the GitHub repository aipotheosis-labs/aci, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aipotheosis-labs/aci
- Repository: https://github.com/aipotheosis-labs/aci

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        DevPortal["Dev Portal (Next.js)"]:::blue
        PythonSDK["Python SDK"]:::blue
    end

    %% Dev Portal Internals
    subgraph "Dev Portal Components"
        direction TB
        Pages["Frontend Pages & Routing"]:::blue
        UIComponents["Frontend UI Components"]:::blue
        APILib["Frontend API Library"]:::blue
    end

    %% API Layer
    subgraph "API Layer (Unified MCP Server)"
        direction TB
        Auth["Authentication & OAuth2 Proxy"]:::blue
        RateLimit["Rate Limiting Middleware"]:::blue
        Quota["Quota Enforcement"]:::blue
        Routes["API Route Handlers"]:::blue
        Executors["Function Executor Subsystem"]:::blue
        CLI["CLI Commands"]:::blue
    end

    %% Persistence & State
    subgraph "Persistence & State"
        direction TB
        DB[(PostgreSQL)]:::blue
        KMS["Secrets & Encryption (KMS)"]:::blue
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AppConnectors["App Connectors\n600+ JSON-driven integrations"]:::orange
        ThirdParty["Third-Party APIs"]:::orange
    end

    %% Deployment / Infrastructure
    subgraph "Deployment / Infra"
        direction TB
        CDK["AWS CDK (VPC, ECS/EKS, RDS, IAM)"]:::green
        CICD["CI/CD (GitHub Actions)"]:::green
    end

    %% Connections
    DevPortal -->|"HTTPS/JSON"| Auth
    PythonSDK -->|"HTTPS/JSON"| Auth

    DevPortal --> Pages
    DevPortal --> UIComponents
    DevPortal --> APILib

    Auth --> RateLimit
    RateLimit --> Quota
    Quota --> Routes
    Routes --> Executors
    Executors --> AppConnectors
    Executors -->|"HTTPS/JSON"| ThirdParty

    Routes -->|"SQL"| DB
    Routes -->|"KMS Encrypt/Decrypt"| KMS
    KMS -->|"Encrypted Data"| DB

    CICD -->|"deploy"| CDK
    CDK -->|"provisions"| Auth
    CDK -->|"provisions"| DB
    CDK -->|"provisions"| KMS
    CDK -->|"provisions"| AppConnectors

    %% Click Events
    click DevPortal "https://github.com/aipotheosis-labs/aci/tree/main/frontend/"
    click Pages "https://github.com/aipotheosis-labs/aci/tree/main/frontend/src/app/"
    click UIComponents "https://github.com/aipotheosis-labs/aci/tree/main/frontend/src/components/"
    click APILib "https://github.com/aipotheosis-labs/aci/tree/main/frontend/src/lib/api/"
    click Auth "https://github.com/aipotheosis-labs/aci/blob/main/backend/aci/server/oauth2.py"
    click RateLimit "https://github.com/aipotheosis-labs/aci/blob/main/backend/aci/server/middleware/ratelimit.py"
    click Quota "https://github.com/aipotheosis-labs/aci/blob/main/backend/aci/server/quota_manager.py"
    click Routes "https://github.com/aipotheosis-labs/aci/tree/main/backend/aci/server/routes/"
    click Executors "https://github.com/aipotheosis-labs/aci/tree/main/backend/aci/server/function_executors/"
    click AppConnectors "https://github.com/aipotheosis-labs/aci/tree/main/backend/aci/server/app_connectors/"
    click CLI "https://github.com/aipotheosis-labs/aci/tree/main/backend/aci/cli/commands/"
    click DB "https://github.com/aipotheosis-labs/aci/tree/main/backend/aci/common/db/"
    click KMS "https://github.com/aipotheosis-labs/aci/blob/main/backend/aci/common/encryption.py"
    click CDK "https://github.com/aipotheosis-labs/aci/tree/main/backend/deployment/"
    click CICD "https://github.com/aipotheosis-labs/aci/tree/main/.github/workflows/"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef green fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef orange fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00;
```
