How gaiin-platform/amplify-genai-backend works
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).