# fadynabil10/ai-salesgrid architecture

> Architecture diagram of the GitHub repository fadynabil10/ai-salesgrid, 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
- Repository: https://github.com/fadynabil10/ai-salesgrid

## Overview

1. **Repository shape**
   - This repo is mostly a packaged architecture reference plus a small Python agent application.
   - The only source code shown is under `agents/ai-salesgrid/` with `agent.py` and `__init__.py`, so the core runtime logic is likely concentrated in a single agent module.
   - The PDFs and diagram folder are part of the architecture deliverable, not just supporting docs.

2. **Primary runtime boundary**
   - The system is a **Python 3.11** service built on the **Google Agent Development Kit (ADK)**.
   - It is intended to run as a **containerized service** via the root `Dockerfile`.
   - Deployment targets **Google Cloud Run**, which makes the orchestration service serverless and HTTP-accessible.

3. **Top-level orchestration pattern**
   - The main architectural concept is a **multi-agent sales orchestrator**.
   - A `root_agent` / “Head Account Manager” acts as the control plane: it receives the sales request, decides which specialist agent should handle each subtask, and aggregates the outputs.
   - This is an agent-to-agent workflow rather than a traditional layered CRUD app.

4. **Specialized sub-agents**
   - The repository describes several domain-specific agents:
     - `solutionagent` for client requirement analysis and mapping needs to company services
     - `pricingagent` for pricing and discount-rule validation
     - `proposalagent` for formal proposal generation
     - `riskagent` for delivery, margin, and compliance assessment
     - `reportingagent` for executive summaries and deal reporting
   - These agents represent the main functional subsystems in the diagram.

5. **Knowledge retrieval flow**
   - The specialist agents are designed to consult **Vertex AI Search** against an internal knowledge base named `company-rules-kb`.
   - This is the main internal policy/service-data boundary: the agents should ground answers in approved company knowledge rather than free-form generation.
   - The root agent also has access to **Google Search** for broader external context, which creates a separate outbound information path.

6. **Enterprise data and integration layer**
   - The README positions the solution as ready to integrate with **CRM systems**, but no concrete CRM adapter code appears in the file tree.
   - The architecture also references **Firestore**, **BigQuery**, and **Cloud Storage** as supporting data services.
   - In diagram terms, these are downstream system boundaries for persistence, analytics, document storage, and sales context enrichment.

7. **Model and AI platform dependency**
   - The generative layer is **Vertex AI** using **Google Gemini `gemini-2.5-flash`**.
   - The model is the reasoning/generation engine inside each agent, while ADK handles agent orchestration and tool use.
   - This means the AI boundary is outside the repo and provided by Google Cloud services.

8. **Configuration and identity**
   - Runtime configuration is driven by environment variables such as `GCP_PROJECT_ID`, `GCP_REGION`, and `GOOGLE_APPLICATION_CREDENTIALS`.
   - The service is expected to run under a Google Cloud service account with roles for Vertex AI, Firestore, BigQuery, Storage, and Cloud Run.
   - This makes identity/authorization a first-class architecture concern.

9. **Deployment path**
   - Local development uses Docker; the production path is Cloud Run.
   - The README also shows an **ADK deployment command** (`adk deploy cloud_run ...`), which implies the agent framework can package and publish the service directly.
   - So the deployment architecture is “build container → run on Cloud Run → connect to Vertex AI and Google data services.”

10. **What is and isn’t implemented in the repo**
   - The repo strongly documents the intended enterprise architecture, but the checked-in code is minimal.
   - There is no visible UI, no explicit API router, and no standalone CRM connector in the file tree.
   - For an architecture diagram, treat the PDFs/README as the authoritative system design and `agent.py` as the implementation anchor for the agent graph.

11. **Best diagram framing**
   - The clearest diagram should show:
     - external user or sales system input
     - the Cloud Run-hosted root agent
     - delegated specialist agents
     - internal knowledge retrieval via Vertex AI Search
     - external Google Search when needed
     - optional enterprise systems: CRM, Firestore, BigQuery, Cloud Storage
     - generated outputs: pricing, proposals, risk scores, and executive reports
   - The key idea is a centralized orchestrator with retrieval-augmented specialist agents, all running in Google Cloud.

Main entry points: [`agents/ai-salesgrid/agent.py`](https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/agent.py) (Head Manager), [`Dockerfile`](https://github.com/fadynabil10/ai-salesgrid/tree/main/Dockerfile) (Docker Image), [`agents/ai-salesgrid/__init__.py`](https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/__init__.py) (Agent Module), [`Architecture Diagram`](https://github.com/fadynabil10/ai-salesgrid/tree/HEAD/Architecture%20Diagram) (Docs & Diagrams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Runtime"]
  node_n1(("Sales Request<br/>external input"))
  node_n2[("Cloud Run<br/>serverless runtime")]
  node_n3["Docker Image<br/>container build"]
  node_n4["ADK Deploy<br/>deployment command"]
end

subgraph group_g2["Orchestration"]
  node_n5{{"Head Manager<br/>root agent<br/>[agent.py]"}}
  node_n6["Agent Module<br/>python package<br/>[__init__.py]"]
  node_n7{{"Solution Agent<br/>specialist agent"}}
  node_n8{{"Pricing Agent<br/>specialist agent"}}
  node_n9{{"Proposal Agent<br/>specialist agent"}}
  node_n10{{"Risk Agent<br/>specialist agent"}}
  node_n11{{"Reporting Agent<br/>specialist agent"}}
end

subgraph group_g3["AI Retrieval"]
  node_n12(("Gemini 2.5 Flash<br/>generative model"))
  node_n13[("Vertex AI Search<br/>retrieval service")]
  node_n14[("Rules KB<br/>knowledge base")]
  node_n15(("Google Search<br/>external search"))
end

subgraph group_g4["Enterprise Data"]
  node_n16[("CRM<br/>enterprise system")]
  node_n17[("Firestore<br/>document store")]
  node_n18[("BigQuery<br/>analytics warehouse")]
  node_n19[("Cloud Storage<br/>object storage")]
end

subgraph group_g5["Repo Artifacts"]
  node_n20["Docs & Diagrams<br/>repo docs"]
end

node_n1 -->|"submit request"| node_n5
node_n3 -->|"run as"| node_n2
node_n4 -->|"deploys"| node_n2
node_n6 -->|"implements"| node_n5
node_n5 -->|"delegate"| node_n7
node_n5 -->|"delegate"| node_n8
node_n5 -->|"delegate"| node_n9
node_n5 -->|"delegate"| node_n10
node_n5 -->|"delegate"| node_n11
node_n7 -->|"retrieve"| node_n13
node_n8 -->|"validate"| node_n13
node_n9 -->|"ground"| node_n13
node_n10 -->|"check"| node_n13
node_n11 -->|"summarize"| node_n13
node_n13 -->|"index"| node_n14
node_n5 -->|"search web"| node_n15
node_n5 -->|"reason with"| node_n12
node_n7 -->|"enrich"| node_n16
node_n8 -->|"persist"| node_n17
node_n11 -->|"analyze"| node_n18
node_n9 -->|"store docs"| node_n19
node_n20 -.->|"documents"| node_n5

click node_n3 "https://github.com/fadynabil10/ai-salesgrid/tree/main/Dockerfile"
click node_n5 "https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/agent.py"
click node_n6 "https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/__init__.py"
click node_n20 "https://github.com/fadynabil10/ai-salesgrid/tree/main/Architecture Diagram"

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_n1,node_n2,node_n3,node_n4 toneBlue
class node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18,node_n19 toneRose
class node_n20 toneIndigo
```

## Components

### Runtime

Containerized agent runtime and deployment boundary

- **Sales Request**: external input · Incoming sales task or question
- **Cloud Run**: serverless runtime · Production hosting target for the agent service
- [Docker Image](https://github.com/fadynabil10/ai-salesgrid/tree/main/Dockerfile): container build · Local and deployable runtime package · `Dockerfile`
- **ADK Deploy**: deployment command · Agent framework deployment path to Cloud Run

### Orchestration

Root agent and specialist agent workflow

- [Head Manager](https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/agent.py): root agent · Central orchestrator that routes work and aggregates results · `agents/ai-salesgrid/agent.py`
- [Agent Module](https://github.com/fadynabil10/ai-salesgrid/blob/main/agents/ai-salesgrid/__init__.py): python package · Implementation anchor for the salesgrid agent runtime · `agents/ai-salesgrid/__init__.py`
- **Solution Agent**: specialist agent · Analyzes client needs and maps them to services
- **Pricing Agent**: specialist agent · Validates pricing, discounting, and margin rules
- **Proposal Agent**: specialist agent · Produces formal proposal content
- **Risk Agent**: specialist agent · Assesses delivery, compliance, and margin risk
- **Reporting Agent**: specialist agent · Summarizes deals for executives and reporting

### AI Retrieval

Model and knowledge grounding services

- **Gemini 2.5 Flash**: generative model · Reasoning and generation engine used by the agents
- **Vertex AI Search**: retrieval service · Grounds agent answers in approved company knowledge
- **Rules KB**: knowledge base · Internal policy and sales knowledge store
- **Google Search**: external search · Broader web context for the root agent

### Enterprise Data

Operational and analytical systems the agents can consult

- **CRM**: enterprise system · Sales context and account integration boundary
- **Firestore**: document store · Operational persistence and context storage
- **BigQuery**: analytics warehouse · Reporting and deal analytics sink
- **Cloud Storage**: object storage · Document and artifact storage boundary

### Repo Artifacts

Packaged architecture reference materials

- [Docs & Diagrams](https://github.com/fadynabil10/ai-salesgrid/tree/HEAD/Architecture%20Diagram): repo docs · Packaged architecture PDFs and diagram assets · `Architecture Diagram`

## Connections

- Sales Request → Head Manager: submit request · A sales request enters the orchestrator
- Docker Image → Cloud Run: run as · Container image is deployed to Cloud Run
- ADK Deploy → Cloud Run: deploys · ADK publishes the agent service to Cloud Run
- Agent Module → Head Manager: implements · Python package contains the root agent implementation
- Head Manager → Solution Agent: delegate · Routes requirements analysis to the solution specialist
- Head Manager → Pricing Agent: delegate · Routes pricing work to the pricing specialist
- Head Manager → Proposal Agent: delegate · Routes proposal drafting to the proposal specialist
- Head Manager → Risk Agent: delegate · Routes risk review to the risk specialist
- Head Manager → Reporting Agent: delegate · Routes executive reporting to the reporting specialist
- Solution Agent → Vertex AI Search: retrieve · Solution analysis is grounded in company knowledge
- Pricing Agent → Vertex AI Search: validate · Pricing rules are checked against internal knowledge
- Proposal Agent → Vertex AI Search: ground · Proposal content uses approved company knowledge
- Risk Agent → Vertex AI Search: check · Risk assessment consults policy and guidance
- Reporting Agent → Vertex AI Search: summarize · Reports are informed by approved knowledge
- Vertex AI Search → Rules KB: index · Vertex AI Search indexes the internal rules base
- Head Manager → Google Search: search web · Root agent can gather broader external context
- Head Manager → Gemini 2.5 Flash: reason with · Agents use Gemini for generation and planning
- Solution Agent → CRM: enrich · Account and opportunity context may come from CRM
- Pricing Agent → Firestore: persist · Operational state can be stored in Firestore
- Reporting Agent → BigQuery: analyze · Executive reporting can feed analytics in BigQuery
- Proposal Agent → Cloud Storage: store docs · Generated proposals and artifacts can be stored in Cloud Storage
- Docs & Diagrams → Head Manager: documents · Repo docs describe the intended architecture and runtime
