# code-dot-org/aiproxy architecture

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

- Interactive diagram: https://gitdiagram.com/code-dot-org/aiproxy
- Repository: https://github.com/code-dot-org/aiproxy

## Overview

##### Project Type & Purpose
- This is a Python-based backend microservice (“AI Proxy”) that exposes an HTTP API (Flask) to wrap LLM calls (OpenAI or AWS Bedrock).
- It runs in Docker containers on AWS ECS Fargate, with infra defined via CloudFormation and delivered via a CodePipeline–CodeBuild CI/CD process.

##### File-Structure Highlights
- `/src` Flask app entry point (`__init__.py`) + route handlers (`assessment.py`, `openai.py`, `test.py`)
- `/lib/assessment` Core business logic: feature extraction, decision trees, labeling, reporting, confidence logic
- `/cicd` Three-phase infra templates & buildspecs:
- phase 1: CICD dependency stack
- phase 2: CICD pipeline stack (CodePipeline, CodeBuild, ECR)
- phase 3: application stack (ECS service, ALB, Secrets Manager, S3 IAM roles)
- `Dockerfile` & `docker-compose.yml` container build & local‐dev orchestration
- `bin/` & `ci-*.sh` test-and-validation scripts
- `tests/` unit, integration, accuracy, and route tests

##### README Insights
- Config via `config.txt` env vars & AWS Secrets Manager
- Local dev: Docker Compose, AWS credentials profile (`aiproxy_development`)
- Rubric Tester CLI (`lib/assessment/rubric_tester.py`): copies S3 data locally (datasets, experiments, releases) and runs accuracy measurements
- Logging → Python `logging` → CloudWatch via ECS log driver
- API docs in `API.md`; testing docs in `TESTING.md`; CICD details in `cicd/README.md`

1. Client → ALB → ECS task → Flask route
2. Flask route → business logic → OpenAI/AWS Bedrock → business logic → Flask response → Client
3. Rubric CLI → local container/lib → S3 (datasets & config) → LLM → local report
4. Git push/PR → CodePipeline → CodeBuild (build, lint, test) → ECR → CloudFormation → ECS update
5. ECS task at startup reads env vars & fetches secrets from Secrets Manager

##### Architectural Patterns & Design Principles
- Layered service pattern (API → service → external)
- Containerized immutability (Docker)
- Infrastructure as code (CloudFormation)
- Automated CI/CD (CodePipeline, CodeBuild)
- Separation of concerns: routing vs. business logic vs. infra

##### Relevant Technologies & Frameworks
- Python 3.11, Flask, Docker, Docker Compose
- AWS ECS Fargate, ECR, CodePipeline, CodeBuild, CloudFormation, S3, Secrets Manager, CloudWatch
- OpenAI Python SDK / AWS Bedrock access
- Pytest for unit/integration tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External" 
        direction TB
        HTTP_Clients["HTTP Clients"]:::external
        CLI_Users["CLI Users (Rubric Tester)"]:::external
    end

    %% Local Development Boundary
    subgraph "Local Dev" 
        direction TB
        Docker_Compose["Docker Compose"]:::compute
        Rubric_CLI["Rubric Tester CLI"]:::compute
    end

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        subgraph "API Layer (Flask)" 
            direction TB
            Flask_Init["__init__.py"]:::compute
            Assessment_Route["assessment.py"]:::compute
            OpenAI_Route["openai.py"]:::compute
            Test_Route["test.py"]:::compute
        end
        subgraph "Business Logic Modules" 
            direction TB
            Assess["assess.py"]:::compute
            Feature_Extractor["code_feature_extractor.py"]:::compute
            Decision_Trees["decision_trees.py"]:::compute
            Labeling["label.py"]:::compute
            Reporting["report.py"]:::compute
            Confidence["confidence.py"]:::compute
            Rubric_Tester["rubric_tester.py"]:::compute
            Config_Module["config.py"]:::compute
        end
    end

    %% AWS Account Boundary
    subgraph "AWS Account" 
        direction TB
        ALB["Application Load Balancer"]:::compute
        ECS["ECS Fargate Service"]:::compute
        CloudWatch["CloudWatch Logs"]:::compute
        S3["S3 Buckets"]:::storage
        Secrets["Secrets Manager"]:::storage
        subgraph "External LLM Service"
            direction TB
            OpenAI["OpenAI API / AWS Bedrock"]:::external
        end
    end

    %% CI/CD Pipeline Boundary
    subgraph "CI/CD Pipeline" 
        direction TB
        GitHub["GitHub"]:::external
        CodePipeline["CodePipeline"]:::cicd
        CodeBuild["CodeBuild"]:::cicd
        ECR["ECR"]:::cicd
        CloudFormation["CloudFormation"]:::cicd
    end

    %% Flows: Client to API
    HTTP_Clients -->|"HTTP POST /assessment"| ALB
    ALB -->|Forward HTTP| ECS
    ECS -->|Invoke Flask Route| Flask_Init

    Flask_Init -->|calls| Assessment_Route
    Flask_Init -->|calls| OpenAI_Route
    Flask_Init -->|calls| Test_Route

    Assessment_Route -->|uses| Assess
    Assessment_Route -->|uses| Feature_Extractor
    Assessment_Route -->|uses| Decision_Trees
    Assessment_Route -->|uses| Labeling
    Assessment_Route -->|uses| Reporting
    Assessment_Route -->|uses| Confidence

    Rubric_CLI -->|reads from| S3
    Rubric_CLI -->|invokes| Rubric_Tester
    Rubric_Tester -->|calls| OpenAI

    Assessment_Route -->|LLM call| OpenAI
    Rubric_Tester -->|LLM call| OpenAI
    ECS -->|logs| CloudWatch

    ECS -->|fetch secrets| Secrets

    %% CI/CD Flow
    GitHub -->|push/PR| CodePipeline
    CodePipeline -->|trigger build| CodeBuild
    CodeBuild -->|push image| ECR
    CodePipeline -->|trigger deploy| CloudFormation
    CloudFormation -->|update| ECS

    %% Local Dev Orchestration
    Docker_Compose -->|runs| Flask_Init
    Docker_Compose -->|runs| Rubric_Tester

    %% Click Events
    click Flask_Init "https://github.com/code-dot-org/aiproxy/blob/main/src/__init__.py"
    click Assessment_Route "https://github.com/code-dot-org/aiproxy/blob/main/src/assessment.py"
    click OpenAI_Route "https://github.com/code-dot-org/aiproxy/blob/main/src/openai.py"
    click Test_Route "https://github.com/code-dot-org/aiproxy/blob/main/src/test.py"
    click Assess "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/assess.py"
    click Feature_Extractor "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/code_feature_extractor.py"
    click Decision_Trees "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/decision_trees.py"
    click Labeling "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/label.py"
    click Reporting "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/report.py"
    click Confidence "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/confidence.py"
    click Rubric_Tester "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/rubric_tester.py"
    click Config_Module "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/config.py"
    click Docker_Compose "https://github.com/code-dot-org/aiproxy/blob/main/docker‐compose.yml"
    click Rubric_CLI "https://github.com/code-dot-org/aiproxy/blob/main/lib/assessment/rubric_tester.py"
    click GitHub "https://github.com/code-dot-org/aiproxy/blob/main/cicd/1-setup/cicd-dependencies.template.yml"
    click CodePipeline "https://github.com/code-dot-org/aiproxy/blob/main/cicd/2-cicd/cicd.template.yml"
    click CodeBuild "https://github.com/code-dot-org/aiproxy/blob/main/cicd/3-app/aiproxy/buildspec.yml"
    click ECR "https://github.com/code-dot-org/aiproxy/blob/main/cicd/3-app/aiproxy/template.yml"
    click CloudFormation "https://github.com/code-dot-org/aiproxy/blob/main/cicd/3-app/aiproxy/template.yml"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#004085,color:#004085
    classDef storage fill:#d4edda,stroke:#155724,color:#155724
    classDef cicd fill:#ffe5b4,stroke:#c97b00,color:#c97b00
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
