How satishvudata98/meridian-agent works
1. System shape
- This is a split frontend/backend serverless application for an autonomous AI research agent.
- The frontend is a Next.js app deployed separately from the AWS backend.
- The backend is composed of multiple AWS Lambda functions behind API Gateway, with supporting AWS services for auth, data, memory, and observability.
2. Frontend boundary
- frontend/ is a Next.js app with pages for the main app, auth callback, run detail views, and digest views.
- It uses apiClient.ts for HTTP calls and useAgentRunStream.ts for live run updates over WebSocket.
- Cognito-specific client logic lives in cognitoAuth.ts, so authentication is handled in the browser and then propagated to backend calls.
- The UI is deployed independently, with environment variables pointing to the backend HTTP API and WebSocket endpoint.
3. Primary backend entrypoints
- backend/lambdas/api/trigger.py is the main entry point to start or trigger an agent run.
- backend/lambdas/api/get_digests.py serves stored digest data to the UI.
- backend/lambdas/api/stream_ticket.py likely issues the short-lived authorization or ticket used for streaming run events to the frontend.
- These API Lambdas form the synchronous HTTP surface for the product.
4. Orchestration layer
- backend/lambdas/orchestrator/handler.py is the central coordination point for agent execution.
- It likely owns the run state machine: receiving triggers, selecting tools, calling the LLM, writing progress, and fan-out to other components.
- This is the key boundary between request handling and the longer-running agent workflow.
5. Execution and safety subsystems
- backend/lambdas/code_executor/handler.py isolates execution of generated code or tool actions.
- backend/lambdas/guardrail/handler.py provides safety or policy checks before or during execution.
- These are separate Lambdas, which creates a clean boundary between orchestration, model reasoning, and risky execution paths.
6. Human-in-the-loop controls
- backend/lambdas/hitl/resume.py and backend/lambdas/hitl/timeout.py support human intervention and time-based continuation/failure handling.
- This implies the agent can pause for approval or escalation, then resume later, rather than being purely fire-and-forget.
- These functions are important for understanding non-linear run lifecycles.
7. Real-time delivery
- backend/lambdas/websocket/handler.py powers the live streaming channel for run progress.
- The frontend subscribes to this channel to receive incremental agent updates instead of waiting for a single final HTTP response.
- This is the main real-time boundary in the architecture.
8. Shared backend services
- backend/shared/ contains cross-cutting logic used by all Lambdas.
- bedrock_client.py, openai_client.py, and llm_factory.py abstract model-provider access; the system is centered on AWS Bedrock but also has OpenAI support.
- memory_store.py encapsulates persistent memory/retrieval behavior.
- tool_executor.py and tool_schemas.py define tool invocation boundaries.
- auth_context.py, run_access.py, and rate_limiter.py handle request identity, authorization to specific runs, and throttling.
- metrics_publisher.py centralizes operational telemetry.
9. Data and infrastructure
- The README and infra files indicate AWS is the main runtime: Lambda, API Gateway, SQS, RDS/PostgreSQL, Bedrock, Cognito, and WebSocket API.
- infra/ is split into stack templates for auth, API, agent, data, memory, network, and observability, so infrastructure is modular rather than one monolithic template.
- The project uses AWS Parameter Store for secrets such as the database password and Tavily API key.
- RDS PostgreSQL is the durable storage layer; the memory stack suggests a dedicated memory/vector-related persistence path as well.
10. Deployment and ops
- CI/CD is handled through GitHub Actions in .github/workflows/, including deployment and cleanup workflows.
- Backend deployment is cloud-native and stack-based, while the frontend is deployed separately on Vercel.
- Operationally, the system expects CloudWatch logs, SQS queues/DLQs, and AWS observability tooling for debugging long-running agent runs.
11. End-to-end data flow
- A user signs in via Cognito, the frontend receives auth state, then calls the HTTP API to trigger a run.
- The orchestrator coordinates the run, uses shared LLM/tool/memory services, and may hand off work to guardrail, code execution, or HITL Lambdas.
- Progress is streamed back over WebSocket to the frontend.
- Final artifacts such as digests and run records are then fetched through the API and rendered in the UI.
12. Architectural takeaway
- The main diagram should show three big zones: the Next.js client, the AWS Lambda/API orchestration layer, and the persistent AWS services behind it.
- The critical boundaries are auth, run orchestration, tool/code execution, human intervention, and streaming updates.
- This is a modular serverless agent platform rather than a single monolithic backend.
Main entry points: handler.py Orchestrator · deploy.yml Deploy Workflow · agent.yaml Agent Stack · api.yaml API Stack
Components 29
Frontend
Next.js client deployed separately from the backend
- Next.js App · Browser client for runs, digests, and auth callback
frontend/src/app - API Client · HTTP wrapper for backend API calls
frontend/src/lib/apiClient.ts - Cognito Auth · Browser-side Cognito authentication and session handling
frontend/src/lib/cognitoAuth.ts - Run Stream · Subscribes to live agent run updates
frontend/src/lib/useAgentRunStream.ts
API Lambdas
Synchronous HTTP entrypoints for the agent platform
- Trigger Run · Starts or triggers an agent run
backend/lambdas/api/trigger.py - Get Digests · Serves stored digest data to the UI
backend/lambdas/api/get_digests.py - Stream Ticket · Issues short-lived streaming authorization
backend/lambdas/api/stream_ticket.py
Orchestration
Core agent execution and safety workflow
- Orchestrator · Coordinates runs, tools, model calls, and state transitions
backend/lambdas/orchestrator/handler.py - Code Executor · Runs generated code or risky tool actions in isolation
backend/lambdas/code_executor/handler.py - Guardrail · Applies policy and safety checks
backend/lambdas/guardrail/handler.py - HITL Resume · Resumes paused runs after approval or intervention
backend/lambdas/hitl/resume.py - HITL Timeout · Handles pause expiry and continuation failure
backend/lambdas/hitl/timeout.py - WebSocket API · Publishes live run events to connected clients
backend/lambdas/websocket/handler.py
Shared Backend
Cross-cutting runtime helpers used by multiple Lambdas
- LLM Factory · Selects and configures model providers
backend/shared/llm_factory.py - Bedrock Client · AWS Bedrock provider integration
backend/shared/bedrock_client.py - OpenAI Client · Fallback or alternate OpenAI provider integration
backend/shared/openai_client.py - Memory Store · Persistent memory and retrieval access
backend/shared/memory_store.py - Tool Executor · Invokes tools from the orchestrator
backend/shared/tool_executor.py - Auth Context · Normalizes caller identity for backend authorization
backend/shared/auth_context.py - Run Access · Authorization checks for specific runs
backend/shared/run_access.py - Metrics · Centralizes operational metric emission
backend/shared/metrics_publisher.py
Infrastructure
Modular AWS stack definitions
- API Stack · API Gateway and Lambda wiring
infra/stacks/api.yaml - Agent Stack · Core agent runtime and workflow resources
infra/stacks/agent.yaml - Auth Stack · Cognito and authentication resources
infra/stacks/auth.yaml - Data Stack · Durable storage and database resources
infra/stacks/data.yaml - Memory Stack · Memory-oriented persistence resources
infra/stacks/memory.yaml - Observability Stack · Logs, metrics, and monitoring resources
infra/stacks/observability.yaml
Delivery Ops
Deployment and maintenance workflows
- Deploy Workflow · Main deployment pipeline
.github/workflows/deploy.yml - Cleanup Workflow · Memory-artifact cleanup pipeline
.github/workflows/cleanup-memory-artifacts.yml
Connections 42
- Next.js App → Cognito Auth: sign in · Browser auth flow begins in Cognito
- Next.js App → API Client: calls · UI fetches backend data and triggers runs
- Next.js App → Run Stream: subscribes · UI listens for live agent updates
- API Client → Trigger Run: trigger run · Starts or resumes agent execution
- API Client → Get Digests: fetch digests · Loads saved digest views
- API Client → Stream Ticket: get ticket · Requests streaming authorization
- Run Stream → WebSocket API: connects · Consumes the live websocket feed
- Trigger Run → Orchestrator: start run · Hands off request to run coordination
- Stream Ticket → WebSocket API: authorize stream · Binds short-lived ticket to websocket access
- Orchestrator → LLM Factory: select model · Chooses provider and model configuration
- Orchestrator → Tool Executor: run tools · Delegates tool invocation boundaries
- Orchestrator → Memory Store: read/write memory · Persists and retrieves run context
- Orchestrator → Guardrail: check safety · Routes sensitive actions through policy checks
- Orchestrator → Code Executor: execute code · Offloads generated code or risky work
- Orchestrator → HITL Resume: pause/resume · Supports human approval loops
- Orchestrator → HITL Timeout: timeout handling · Handles paused run expiry
- Orchestrator → WebSocket API: emit events · Publishes progress to streaming clients
- LLM Factory → Bedrock Client: uses · Primary model provider integration
- LLM Factory → OpenAI Client: fallback · Alternate provider integration
- Tool Executor → Auth Context: verify caller · Checks request identity before tool use
- Tool Executor → Run Access: authorize run · Ensures caller can act on the run
- Orchestrator → Metrics: telemetry · Emits operational metrics for runs
- Auth Stack → Cognito Auth: identity source · Provides Cognito-based sign-in
- API Stack → Trigger Run: hosts · Deploys HTTP trigger endpoint
- API Stack → Get Digests: hosts · Deploys digest retrieval endpoint
- API Stack → Stream Ticket: hosts · Deploys streaming ticket endpoint
- API Stack → WebSocket API: hosts · Deploys websocket entrypoint
- Agent Stack → Orchestrator: runs · Defines core agent workflow resources
- Agent Stack → Code Executor: runs · Defines isolated execution resources
- Agent Stack → Guardrail: runs · Defines safety function resources
- Agent Stack → HITL Resume: runs · Defines approval-resume resources
- Agent Stack → HITL Timeout: runs · Defines pause-timeout resources
- Data Stack → Memory Store: persists · Backs durable run and artifact storage
- Memory Stack → Memory Store: persists · Backs memory-specific persistence
- Observability Stack → Metrics: collects · Receives logs and metrics for operations
- Deploy Workflow → API Stack: deploys · CI/CD applies backend API infrastructure
- Deploy Workflow → Agent Stack: deploys · CI/CD applies core agent infrastructure
- Deploy Workflow → Auth Stack: deploys · CI/CD applies auth infrastructure
- Deploy Workflow → Data Stack: deploys · CI/CD applies data infrastructure
- Deploy Workflow → Memory Stack: deploys · CI/CD applies memory infrastructure
- Deploy Workflow → Observability Stack: deploys · CI/CD applies monitoring infrastructure
- Cleanup Workflow → Memory Stack: cleans · Removes stale memory artifacts