# gaiin-platform/amplify-genai-backend architecture

> Architecture diagram of the GitHub repository gaiin-platform/amplify-genai-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaiin-platform/amplify-genai-backend
- Repository: https://github.com/gaiin-platform/amplify-genai-backend

## Overview

##### Project Type & Purpose
- This is a mono‑repo of serverless microservices (Node.js and Python) that implements Amplify GenAI back‑end functionality.
- Your focus: the “amplify‑lambda‑js” service—an independent chat endpoint that the frontend pings for conversational AI.

##### File‑Structure Analysis of amplify‑lambda‑js
- Top‑Level:
- index.js / indexApiG.js – Lambda entry points (API Gateway handlers)
- serverless.yml – Defines the ChatEndpoint HTTP event, associated Lambda, IAM roles, SQS queues, and Step Functions.
- package.json / package-lock.json – Node dependencies.
- Key Subdirectories:
- common/ – shared utility modules (logging, encoding, permissions, LLM wrappers, chat controllers and handlers, multiplexer).
- assistants/ – logic to enqueue tasks, route to different assistant types, manage state machines.
- azure/ & bedrock/ – connectors for Azure OpenAI and AWS Bedrock.
- queue/ – message definitions for SQS.
- statemachine/ – Step Functions state definitions and orchestrator code.
- workflow/ – workflow builder, custom chat/workflow composer.

##### Extracted Workflow (ChatEndpoint)
1. Frontend issues HTTP POST to ChatEndpoint (API Gateway).
2. API Gateway invokes Lambda (indexApiG.js).
3. The Lambda:
a. Normalizes input via common/handlers and param validation.
b. Determines routing: simple chat vs. data‑augmented vs. multi‑assistant via common/chat/controllers.
c. For complex cases: pushes a message to SQS (assistantQueueRouter.js) or invokes a Step Functions state machine.
d. For immediate responses: calls LLM connectors in azure/openai.js or bedrock/bedrock.js.
4. Worker Lambdas (triggered by SQS or Step Functions):
a. Pull tasks, run assistant logic (assistants/*), manage intermediate states.
b. Use common/multiplexer to fan‑out or aggregate multi‑model responses.
c. Log usage, optionally write artifacts or reports via assistants/reportWriter.js.
5. Final result flows back:
- If sync: directly returned to the caller via API Gateway.
- If async (state machine): the frontend polls a status endpoint or receives a push via WebSocket / callback.

##### Components
- Frontend (React/Vue)
- AWS API Gateway (ChatEndpoint)
- Lambda: ChatHandler (indexApiG.js)
- Internal Modules (grouped inside the Lambda):
- common handlers & controllers
- workflow/assistant routing
- LLM connectors (Azure OpenAI, AWS Bedrock)
- multiplexer
- SQS Queue for async tasks
- Step Functions state machine
- Worker Lambdas (assistants, report writers)
- External Services: Azure OpenAI endpoint, AWS Bedrock endpoint
- (Optional) Data stores or artifact buckets if used

##### Architectural Patterns & Principles
- Serverless microservices (Each function is single‑purpose)
- Event‑driven: SQS for async decoupling, Step Functions for orchestration
- Layered in‑Lambda modules: controllers → routers → connectors → multiplexer
- Configurable via serverless‑compose for environment variable reuse

##### Deliverables
- (Optional) A zoomed‑in inset of the Lambda’s internal module graph (controllers → routers → connectors).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Layer
    FE["Frontend (React/Vue)"]:::blue
    APIG["AWS API Gateway\nChatEndpoint"]:::blue
    FE -->|"1. POST /chat"| APIG

    %% Lambda Handler
    ChatHandler["ChatHandler Lambda\n(indexApiG.js)"]:::blue
    APIG -->|"2. Invoke"| ChatHandler
    click ChatHandler "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/indexApiG.js"

    %% Internal Logic Modules
    subgraph "Internal Logic" 
        direction TB
        Handlers["Input Normalization"]:::green
        click Handlers "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/common/handlers.js"
        Params["Param Handling"]:::green
        click Params "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/common/params.js"
        Validate["Parameter Validation"]:::green
        click Validate "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/common/validate.js"
        AssistantRouter["Assistant Queue Router"]:::green
        click AssistantRouter "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/assistantQueueRouter.js"
        ChatControllers["Chat Controllers"]:::green
        click ChatControllers "https://github.com/gaiin-platform/amplify-genai-backend/tree/main/amplify-lambda-js/common/chat/controllers/"
        ChatEvents["Chat Events"]:::green
        click ChatEvents "https://github.com/gaiin-platform/amplify-genai-backend/tree/main/amplify-lambda-js/common/chat/events/"
        RAG["RAG Helper"]:::green
        click RAG "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/common/chat/rag/rag.js"
        Multiplexer["Multiplexer"]:::green
        click Multiplexer "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/common/multiplexer.js"
        
        %% Connectors
        subgraph "LLM Connectors"
            direction TB
            AzureConnector["Azure OpenAI Connector"]:::green
            click AzureConnector "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/azure/openai.js"
            BedrockConnector["AWS Bedrock Connector"]:::green
            click BedrockConnector "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/bedrock/bedrock.js"
        end
    end

    ChatHandler -->|"3a. Normalize & Validate"| Handlers --> Params --> Validate
    Validate -->|"3b. Route"| ChatControllers
    ChatControllers -->|"determine sync vs async"| AssistantRouter

    %% Sync Path
    ChatControllers -->|"Sync path"| AzureConnector
    ChatControllers -->|"Sync path"| BedrockConnector
    AzureConnector -->|"4. Call Azure OpenAI"| Multiplexer
    BedrockConnector -->|"4. Call Bedrock"| Multiplexer
    Multiplexer -->|"5. Aggregate"| ChatHandler
    ChatHandler -->|"6. Return Response"| APIG
    APIG -->|"7. 200 OK"| FE

    %% Async Path
    AssistantRouter -->|"Enqueue message"| SQS
    click SQS "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/assistants/queue/messages.js"
    SQS["SQS Queue"]:::orange
    SQS -->|"8. Trigger Worker"| Worker
    Worker["Worker Lambdas"]:::blue
    Worker -->|"9. Orchestrate"| SFN
    click SFN "https://github.com/gaiin-platform/amplify-genai-backend/blob/main/amplify-lambda-js/assistants/statemachine/states.js"
    SFN["Step Functions"]:::orange
    SFN -->|"10. Fan‑out/Aggregate"| Multiplexer
    Multiplexer -->|"11. Send to Callback/Status"| StatusEndpoint
    StatusEndpoint["Status Endpoint / WebSocket"]:::blue
    StatusEndpoint --> FE

    %% External Services
    AzureExt["Azure OpenAI Service"]:::red
    BedrockExt["AWS Bedrock Service"]:::red
    AzureConnector -->|"HTTP call"| AzureExt
    BedrockConnector -->|"HTTP call"| BedrockExt

    %% Styles
    classDef blue fill:#B3C7E6,stroke:#2F4F4F,color:#000;
    classDef green fill:#C7E6B3,stroke:#2F4F4F,color:#000;
    classDef orange fill:#E6B38F,stroke:#2F4F4F,color:#000;
    classDef red fill:#E6B3B3,stroke:#2F4F4F,color:#000;
```
