# fadynabil10/ai-salesgrid-on-aws architecture

> Architecture diagram of the GitHub repository fadynabil10/ai-salesgrid-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fadynabil10/ai-salesgrid-on-aws
- Repository: https://github.com/fadynabil10/ai-salesgrid-on-aws

## Overview

1. **Repository purpose**
   - This repo is a two-part AWS-hosted sales automation system: a **Streamlit chat frontend** and a **backend Amazon Nova agent** that performs multi-agent sales orchestration.

2. **Top-level architecture**
   - The main request path is: **user in Streamlit UI → AWS API Gateway → Nova/Bedrock agent backend → response back through API Gateway → Streamlit UI**.
   - The README positions API Gateway as the secure boundary between the UI and the agent runtime.

3. **Frontend subsystem: `2- Streamlit Frontend/`**
   - This is the interactive operator-facing application.
   - `app.py` is the entry point and likely owns the chat UI, request submission, and rendering of agent responses.
   - `requirements.txt` and `Dockerfile` show it is meant to run as a containerized Python 3.8 Streamlit app.

4. **Frontend dependencies and responsibilities**
   - The frontend uses **Streamlit** for UI, **requests** for HTTP calls, and **boto3/botocore** for AWS SigV4-authenticated access to API Gateway.
   - Its architectural role is thin-client orchestration: it does not contain sales logic, only input collection, API invocation, and response display.

5. **Backend subsystem: `3- Amazon Nova Agent/`**
   - This is the intelligence layer and is containerized separately from the UI.
   - `agents/ai-salesgrid/agent.py` is the core agent implementation; `__init__.py` makes it a Python package.
   - The backend is described as an AWS Bedrock / Amazon Nova-based agent that can orchestrate specialized sub-agents.

6. **Backend responsibilities**
   - The agent is responsible for sales workflow intelligence: requirement analysis, pricing, proposal generation, risk assessment, and executive summaries.
   - The README indicates rule-based validation around pricing, discounts, margins, approvals, and compliance, so the backend is more than simple text generation.

7. **Agent runtime and integration surface**
   - The backend is designed to talk to **Amazon Nova** using an API key and is described as using the `openai` client against `https://api.nova.amazon.com/v1`.
   - The Dockerfile suggests an **ADK-style agent runtime** (`adk` implied), so the backend is intended to run as a packaged agent service rather than a direct library call.

8. **AWS boundary and deployment model**
   - AWS services are the main infrastructure boundary: **API Gateway** for ingress, **IAM** for auth, and likely **ECS/EKS/Lambda** for hosting the agent.
   - The README also references **Bedrock agents, knowledge base, and Flow**, indicating the backend may rely on AWS-managed AI orchestration and retrieval components.

9. **Configuration and secrets flow**
   - Frontend configuration is driven by environment variables for AWS credentials and the API Gateway URL.
   - Backend configuration is driven by an Amazon Nova API key and an agent ID.
   - This makes the architecture environment-driven and container-friendly, with no checked-in secrets.

10. **Documentation and architecture artifacts**
   - The `1- Architecture Diagram/` folder and the two PDFs are not runtime code, but they are important architectural references.
   - They likely define the intended agent topology, AWS deployment choices, and any CRM extension points.

11. **Data flow and trust boundaries**
   - User prompts enter only through Streamlit.
   - All backend execution happens behind AWS API Gateway, which is the main trust boundary.
   - Any external knowledge, CRM data, or sales rules are conceptually consumed by the agent layer, not the frontend.

12. **What to show in an architecture diagram**
   - Separate the diagram into:
     - **Presentation layer:** Streamlit container
     - **API/security layer:** API Gateway + IAM
     - **AI orchestration layer:** Nova/Bedrock agent container/runtime
     - **Optional enterprise data layer:** knowledge base / CRM / persistence, if depicted from the PDFs
   - Also show the two Dockerized deployables as independent units with different runtime responsibilities.

Main entry points: [`2- Streamlit Frontend/app.py`](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/2-%20Streamlit%20Frontend/app.py) (Streamlit app), [`3- Amazon Nova Agent/agents/ai-salesgrid/agent.py`](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/3-%20Amazon%20Nova%20Agent/agents/ai-salesgrid/agent.py) (Nova agent), [`README.md`](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/README.md) (README), [`2- Streamlit Frontend/Dockerfile`](https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/HEAD/2-%20Streamlit%20Frontend/Dockerfile) (UI container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs & diagrams"]
  node_readme["README<br/>project guide<br/>[README.md]"]
  node_arch_diagram["Diagram assets<br/>architecture refs"]
  node_pdf_solution["AWS solution PDF<br/>architecture doc"]
  node_pdf_deployment["AWS deploy PDF<br/>deployment doc"]
end

subgraph group_frontend["Streamlit frontend"]
  node_streamlit_app["Streamlit app<br/>ui entrypoint<br/>[app.py]"]
  node_frontend_docker["UI container<br/>container spec"]
  node_frontend_deps["UI deps<br/>python deps<br/>[requirements.txt]"]
end

subgraph group_boundary["AWS boundary"]
  node_api_gateway{{"API Gateway<br/>aws ingress"}}
  node_iam_auth(("IAM auth<br/>aws auth"))
end

subgraph group_backend["Nova agent backend"]
  node_nova_agent["Nova agent<br/>agent runtime<br/>[agent.py]"]
  node_agent_pkg["Agent package<br/>python package<br/>[__init__.py]"]
  node_backend_docker["Agent container<br/>container spec"]
  node_sales_orchestration{{"Sales orchestration<br/>workflow engine<br/>[agent.py]"}}
  node_pricing_rules(("Pricing rules<br/>validation logic<br/>[agent.py]"))
end

subgraph group_external["External services"]
  node_nova_api{{"Nova API<br/>llm service"}}
  node_bedrock_tools{{"Bedrock tools<br/>managed ai"}}
  node_enterprise_data[("Enterprise data<br/>kb/crm data")]
end

node_readme -->|"describes"| node_streamlit_app
node_readme -->|"describes"| node_nova_agent
node_readme -->|"positions"| node_api_gateway
node_streamlit_app -->|"calls"| node_api_gateway
node_frontend_deps -.->|"supports"| node_streamlit_app
node_frontend_docker -.->|"packages"| node_streamlit_app
node_streamlit_app -->|"signs requests"| node_iam_auth
node_api_gateway -->|"enforces"| node_iam_auth
node_api_gateway -->|"routes to"| node_nova_agent
node_backend_docker -.->|"packages"| node_nova_agent
node_agent_pkg -.->|"exposes"| node_nova_agent
node_nova_agent -->|"drives"| node_sales_orchestration
node_nova_agent -->|"applies"| node_pricing_rules
node_sales_orchestration -->|"invokes"| node_nova_api
node_sales_orchestration -.->|"integrates"| node_bedrock_tools
node_sales_orchestration -.->|"consumes"| node_enterprise_data
node_bedrock_tools -.->|"retrieves"| node_enterprise_data
node_api_gateway -->|"returns"| node_streamlit_app

click node_readme "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/README.md"
click node_arch_diagram "https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/main/1- Architecture Diagram"
click node_pdf_solution "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/AI SalesGrid - Solution on AWS.pdf"
click node_pdf_deployment "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/AI SalesGrid - Tech Deployment on AWS.pdf"
click node_streamlit_app "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/2- Streamlit Frontend/app.py"
click node_frontend_docker "https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/main/2- Streamlit Frontend/Dockerfile"
click node_frontend_deps "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/2- Streamlit Frontend/requirements.txt"
click node_nova_agent "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/3- Amazon Nova Agent/agents/ai-salesgrid/agent.py"
click node_agent_pkg "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/3- Amazon Nova Agent/agents/ai-salesgrid/__init__.py"
click node_backend_docker "https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/main/3- Amazon Nova Agent/Dockerfile"
click node_sales_orchestration "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/3- Amazon Nova Agent/agents/ai-salesgrid/agent.py"
click node_pricing_rules "https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/3- Amazon Nova Agent/agents/ai-salesgrid/agent.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_readme,node_arch_diagram,node_pdf_solution,node_pdf_deployment toneBlue
class node_streamlit_app,node_frontend_docker,node_frontend_deps toneAmber
class node_api_gateway,node_iam_auth toneMint
class node_nova_agent,node_agent_pkg,node_backend_docker,node_sales_orchestration,node_pricing_rules toneRose
class node_nova_api,node_bedrock_tools,node_enterprise_data toneIndigo
```

## Components

### Docs & diagrams

Architecture references and solution documentation

- [README](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/main/README.md): project guide · Top-level overview of the solution and its deployment model · `README.md`
- [Diagram assets](https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/HEAD/1-%20Architecture%20Diagram): architecture refs · Repository folder containing architectural diagrams · `1- Architecture Diagram`
- [AWS solution PDF](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/AI%20SalesGrid%20-%20Solution%20on%20AWS.pdf): architecture doc · Solution architecture reference document · `AI SalesGrid - Solution on AWS.pdf`
- [AWS deploy PDF](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/AI%20SalesGrid%20-%20Tech%20Deployment%20on%20AWS.pdf): deployment doc · Deployment-oriented architecture reference document · `AI SalesGrid - Tech Deployment on AWS.pdf`

### Streamlit frontend

Operator-facing chat application

- [Streamlit app](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/2-%20Streamlit%20Frontend/app.py): ui entrypoint · Operator chat interface and request submission flow · `2- Streamlit Frontend/app.py`
- [UI container](https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/HEAD/2-%20Streamlit%20Frontend/Dockerfile): container spec · Container definition for the Streamlit frontend runtime · `2- Streamlit Frontend/Dockerfile`
- [UI deps](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/2-%20Streamlit%20Frontend/requirements.txt): python deps · Frontend runtime dependencies and AWS client libraries · `2- Streamlit Frontend/requirements.txt`

### AWS boundary

Ingress, auth, and service exposure layer

- **API Gateway**: aws ingress · Secure HTTP boundary between UI and agent runtime
- **IAM auth**: aws auth · AWS authentication and request authorization boundary

### Nova agent backend

AI orchestration and sales workflow service

- [Nova agent](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/3-%20Amazon%20Nova%20Agent/agents/ai-salesgrid/agent.py): agent runtime · Backend containerized agent service · `3- Amazon Nova Agent/agents/ai-salesgrid/agent.py`
- [Agent package](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/3-%20Amazon%20Nova%20Agent/agents/ai-salesgrid/__init__.py): python package · Package wrapper for the sales agent implementation · `3- Amazon Nova Agent/agents/ai-salesgrid/__init__.py`
- [Agent container](https://github.com/fadynabil10/ai-salesgrid-on-aws/tree/HEAD/3-%20Amazon%20Nova%20Agent/Dockerfile): container spec · Container definition for the backend agent runtime · `3- Amazon Nova Agent/Dockerfile`
- [Sales orchestration](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/3-%20Amazon%20Nova%20Agent/agents/ai-salesgrid/agent.py): workflow engine · Coordinates requirement analysis, proposal drafting, and summaries · `3- Amazon Nova Agent/agents/ai-salesgrid/agent.py`
- [Pricing rules](https://github.com/fadynabil10/ai-salesgrid-on-aws/blob/HEAD/3-%20Amazon%20Nova%20Agent/agents/ai-salesgrid/agent.py): validation logic · Rule-based checks for pricing, discounts, margins, and approvals · `3- Amazon Nova Agent/agents/ai-salesgrid/agent.py`

### External services

Managed AI and enterprise data dependencies

- **Nova API**: llm service · Amazon Nova model endpoint used by the backend agent
- **Bedrock tools**: managed ai · AWS-managed agent orchestration and knowledge components
- **Enterprise data**: kb/crm data · External knowledge base, CRM, or sales data consumed by the agent

## Connections

- README → Streamlit app: describes · README documents the frontend app role
- README → Nova agent: describes · README documents the backend agent role
- README → API Gateway: positions · README identifies API Gateway as the trust boundary
- Streamlit app → API Gateway: calls · Frontend submits user prompts through the gateway
- UI deps → Streamlit app: supports · Dependencies enable Streamlit UI and AWS client calls
- UI container → Streamlit app: packages · Containerizes the UI application
- Streamlit app → IAM auth: signs requests · Frontend uses AWS-authenticated access patterns
- API Gateway → IAM auth: enforces · Gateway applies request authentication and authorization
- API Gateway → Nova agent: routes to · Gateway forwards requests to the backend agent service
- Agent container → Nova agent: packages · Containerizes the agent runtime
- Agent package → Nova agent: exposes · Package wrapper exposes the agent implementation
- Nova agent → Sales orchestration: drives · Core agent logic coordinates sales workflows
- Nova agent → Pricing rules: applies · Agent enforces pricing and approval constraints
- Sales orchestration → Nova API: invokes · Agent calls Amazon Nova for generation and reasoning
- Sales orchestration → Bedrock tools: integrates · Agent can use Bedrock-managed orchestration and knowledge features
- Sales orchestration → Enterprise data: consumes · Agent may retrieve external knowledge or CRM context
- Bedrock tools → Enterprise data: retrieves · Managed AI layer can surface enterprise knowledge to the agent
- API Gateway → Streamlit app: returns · Responses flow back to the UI after backend execution
