# kaushaldesai04/sfn-agentic-workflow-automation architecture

> Architecture diagram of the GitHub repository kaushaldesai04/sfn-agentic-workflow-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaushaldesai04/sfn-agentic-workflow-automation
- Repository: https://github.com/kaushaldesai04/sfn-agentic-workflow-automation

## Overview

This is an AWS CDK application for bounded, agent-assisted business request routing. A client submits a request through API Gateway; the request handler starts a Standard Step Functions workflow, which validates input, invokes a Bedrock Agent, deterministically validates its recommendation, then routes eligible decisions to destination queues and persists results. Invalid inputs and agent failures are handled in the workflow. The graph also shows the contracts, persistence, and monitoring layers. Lambda internals are included where the source index establishes their responsibilities; some service wiring is visible only in the infrastructure excerpts.

Main entry points: [`agentic_workflow/constructs/workflow.py`](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/workflow.py) (Step Functions workflow), [`agentic_workflow/stack.py`](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/stack.py) (Application stack), [`agentic_workflow/constructs/monitoring.py`](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/monitoring.py) (Monitoring and alarms), [`agentic_workflow/constructs/api.py`](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/api.py) (API Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Request ingress"]
  node_api["API Gateway<br/>[api.py]"]
  node_request_handler["Request handler<br/>[handler.py]"]
  node_request_contract["Workflow request contract"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_workflow["Step Functions workflow<br/>[workflow.py]"]
  node_input_validator["Request validation<br/>[handler.py]"]
  node_decision_validator["Decision policy validator<br/>[handler.py]"]
  node_policy["Routing policy<br/>[policy.py]"]
end

subgraph group_agent["Agent decisioning"]
  node_adapter["Bedrock adapter<br/>[handler.py]"]
  node_agent_invocation["Agent invocation<br/>[invoke_agent.py]"]
  node_response_parser["Response parser<br/>[response_parser.py]"]
  node_bedrock_agent["Bedrock Agent<br/>[bedrock_agent.py]"]
  node_decision_contract["Agent decision contract<br/>[agent_decision.py]"]
end

subgraph group_outcomes["Routing and results"]
  node_queues["Destination queues<br/>[data.py]"]
  node_result_persister["Result persister<br/>[handler.py]"]
  node_results_table[("Results table<br/>[data.py]")]
end

subgraph group_operations["Configuration and monitoring"]
  node_monitoring["Monitoring and alarms<br/>[monitoring.py]"]
  node_config["Environment configuration<br/>[config.py]"]
  node_stack["Application stack<br/>[stack.py]"]
end

node_client(("Request client"))

node_client -->|"submits request"| node_api
node_api -->|"routes POST"| node_request_handler
node_request_handler -->|"validates request"| node_request_contract
node_request_handler -->|"starts execution"| node_workflow
node_workflow -->|"invokes first"| node_input_validator
node_workflow -->|"invokes agent task"| node_adapter
node_adapter -->|"delegates invocation"| node_agent_invocation
node_adapter -->|"parses completion"| node_response_parser
node_agent_invocation -.->|"invokes agent"| node_bedrock_agent
node_response_parser -->|"validates decision"| node_decision_contract
node_workflow -->|"validates recommendation"| node_decision_validator
node_decision_validator -->|"checks decision"| node_decision_contract
node_decision_validator -->|"applies policy"| node_policy
node_workflow -->|"sends routed message"| node_queues
node_workflow -->|"invokes persistence"| node_result_persister
node_workflow -->|"grants write access"| node_results_table
node_result_persister -.->|"writes result"| node_results_table
node_monitoring -->|"monitors executions"| node_workflow
node_monitoring -->|"monitors errors"| node_api
node_monitoring -->|"alarms on queues"| node_queues
node_stack -->|"assembles construct"| node_workflow
node_stack -->|"assembles construct"| node_api
node_stack -->|"assembles construct"| node_monitoring
node_stack -->|"passes configuration"| node_config

click node_api "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/api.py"
click node_request_handler "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/request_handler/handler.py"
click node_request_contract "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/contracts/workflow_request.py"
click node_workflow "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/workflow.py"
click node_input_validator "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/validate_request/handler.py"
click node_adapter "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/handler.py"
click node_agent_invocation "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/invoke_agent.py"
click node_response_parser "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/response_parser.py"
click node_bedrock_agent "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/bedrock_agent.py"
click node_decision_contract "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/contracts/agent_decision.py"
click node_decision_validator "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/validate_decision/handler.py"
click node_policy "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/policy.py"
click node_queues "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/data.py"
click node_result_persister "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/persist_result/handler.py"
click node_results_table "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/data.py"
click node_monitoring "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/monitoring.py"
click node_config "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/config.py"
click node_stack "https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/stack.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_request_handler,node_request_contract,node_client toneBlue
class node_workflow,node_input_validator,node_decision_validator,node_policy toneAmber
class node_adapter,node_agent_invocation,node_response_parser,node_bedrock_agent,node_decision_contract toneMint
class node_queues,node_result_persister,node_results_table toneRose
class node_monitoring,node_config,node_stack toneIndigo
```

## Components

### Request ingress

- [API Gateway](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/api.py): `agentic_workflow/constructs/api.py`
- [Request handler](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/request_handler/handler.py): `functions/request_handler/handler.py`
- [Workflow request contract](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/contracts/workflow_request.py): `shared/contracts/workflow_request.py`

### Workflow orchestration

- [Step Functions workflow](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/workflow.py): `agentic_workflow/constructs/workflow.py`
- [Request validation](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/validate_request/handler.py): `functions/validate_request/handler.py`
- [Decision policy validator](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/validate_decision/handler.py): `functions/validate_decision/handler.py`
- [Routing policy](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/policy.py): `shared/policy.py`

### Agent decisioning

- [Bedrock adapter](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/handler.py): `functions/bedrock_adapter/handler.py`
- [Agent invocation](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/invoke_agent.py): `functions/bedrock_adapter/invoke_agent.py`
- [Response parser](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/bedrock_adapter/response_parser.py): `functions/bedrock_adapter/response_parser.py`
- [Bedrock Agent](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/bedrock_agent.py): `agentic_workflow/constructs/bedrock_agent.py`
- [Agent decision contract](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/shared/contracts/agent_decision.py): `shared/contracts/agent_decision.py`

### Routing and results

- [Destination queues](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/data.py): `agentic_workflow/constructs/data.py`
- [Result persister](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/functions/persist_result/handler.py): `functions/persist_result/handler.py`
- [Results table](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/data.py): `agentic_workflow/constructs/data.py`

### Configuration and monitoring

- [Monitoring and alarms](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/constructs/monitoring.py): `agentic_workflow/constructs/monitoring.py`
- [Environment configuration](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/config.py): `agentic_workflow/config.py`
- [Application stack](https://github.com/kaushaldesai04/sfn-agentic-workflow-automation/blob/main/agentic_workflow/stack.py): `agentic_workflow/stack.py`

### Other components

- **Request client**

## Connections

- Request client → API Gateway: submits request (evidence: `README.md`)
- API Gateway → Request handler: routes POST (evidence: `agentic_workflow/constructs/api.py`)
- Request handler → Workflow request contract: validates request (evidence: `functions/request_handler/handler.py`)
- Request handler → Step Functions workflow: starts execution (evidence: `agentic_workflow/constructs/workflow.py`)
- Step Functions workflow → Request validation: invokes first (evidence: `agentic_workflow/constructs/workflow.py`)
- Step Functions workflow → Bedrock adapter: invokes agent task (evidence: `agentic_workflow/constructs/workflow.py`)
- Bedrock adapter → Agent invocation: delegates invocation (evidence: `functions/bedrock_adapter/handler.py`)
- Bedrock adapter → Response parser: parses completion (evidence: `functions/bedrock_adapter/handler.py`)
- Agent invocation → Bedrock Agent: invokes agent
- Response parser → Agent decision contract: validates decision (evidence: `functions/bedrock_adapter/response_parser.py`)
- Step Functions workflow → Decision policy validator: validates recommendation (evidence: `agentic_workflow/constructs/workflow.py`)
- Decision policy validator → Agent decision contract: checks decision (evidence: `functions/validate_decision/handler.py`)
- Decision policy validator → Routing policy: applies policy (evidence: `functions/validate_decision/handler.py`)
- Step Functions workflow → Destination queues: sends routed message (evidence: `agentic_workflow/constructs/workflow.py`)
- Step Functions workflow → Result persister: invokes persistence (evidence: `agentic_workflow/constructs/workflow.py`)
- Step Functions workflow → Results table: grants write access (evidence: `agentic_workflow/constructs/workflow.py`)
- Result persister → Results table: writes result
- Monitoring and alarms → Step Functions workflow: monitors executions (evidence: `agentic_workflow/constructs/monitoring.py`)
- Monitoring and alarms → API Gateway: monitors errors (evidence: `agentic_workflow/constructs/monitoring.py`)
- Monitoring and alarms → Destination queues: alarms on queues (evidence: `agentic_workflow/constructs/monitoring.py`)
- Application stack → Step Functions workflow: assembles construct (evidence: `agentic_workflow/stack.py`)
- Application stack → API Gateway: assembles construct (evidence: `agentic_workflow/stack.py`)
- Application stack → Monitoring and alarms: assembles construct (evidence: `agentic_workflow/stack.py`)
- Application stack → Environment configuration: passes configuration (evidence: `agentic_workflow/stack.py`)