# rahulbalhotra-ship-it/kpmg_ai_team architecture

> Architecture diagram of the GitHub repository rahulbalhotra-ship-it/kpmg_ai_team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulbalhotra-ship-it/kpmg_ai_team
- Repository: https://github.com/rahulbalhotra-ship-it/kpmg_ai_team

## Overview

1. **Overall shape**
   - This repository is a **workspace scaffold** for a multi-component product, not a single app.
   - It is organized around three runtime surfaces: a **Python agent system**, a **backend service layer**, and a **browser-based frontend**.
   - Supporting folders provide **shared contracts**, **database assets**, **docs**, and **deployment scaffolding**.

2. **Agent orchestration layer**
   - The `agents/` package is the core AI/workflow domain.
   - It contains individual role-based agents such as `director`, `pm`, `design`, `dev`, `qa`, `consultant`, and `partner`, suggesting a **multi-agent collaboration model**.
   - `agents/agents/graph.py`, `state.py`, `parser.py`, `generators.py`, and `llm.py` indicate that this layer manages **stateful agent execution**, prompt parsing, output generation, and LLM interaction.

3. **Agent workflows and tools**
   - `agents/prompts/` stores prompt templates per agent role, which are part of the agent behavior boundary.
   - `agents/tools/` includes `linter.py` and `test_runner.py`, so agents can trigger or evaluate code-quality and test-related actions.
   - `agents/workflows/` and `agents/graphs/` are placeholders for higher-level orchestration pipelines and graph definitions.

4. **Backend service boundary**
   - The `backend/` directory appears to be a separate Python service that exposes application functionality to the rest of the system.
   - `backend/app/main.py`, `agent.py`, and `logger.py` suggest an application entrypoint, an agent-facing integration layer, and centralized logging.
   - `backend/src/api`, `services`, `db`, `middleware`, and `sockets` indicate a conventional backend split into **API handlers**, **business logic**, **data access**, **cross-cutting middleware**, and **real-time communication**.

5. **Backend and agent integration**
   - The presence of `backend/langgraph/` strongly suggests the backend integrates with a **graph-based agent orchestration runtime**.
   - This likely makes the backend the boundary between external clients and the internal agent system, translating requests into agent workflows and returning structured results.
   - `backend/uploads/` implies the backend also handles file intake or artifact storage related to workflows.

6. **Frontend application surface**
   - The `frontend/` folder contains a browser UI with `index.html`, `game.js`, `assets.js`, `style.css`, and a `src/` tree.
   - The `src/components/chat`, `agents`, and `office` folders suggest the UI is organized around **conversation**, **agent visibility/control**, and some kind of **workspace/office metaphor**.
   - `src/store`, `hooks`, `lib`, and `types` indicate a client-side app with local state management and typed domain models.

7. **Shared contracts**
   - `shared/constants`, `shared/schemas`, and `shared/types` are intended to hold cross-cutting definitions used by more than one layer.
   - This is the key boundary for keeping the frontend, backend, and agents aligned on the same message shapes and domain concepts.
   - For an architecture diagram, this should be shown as a **shared contract layer** connecting multiple runtimes.

8. **Data and persistence**
   - `database/migrations` and `database/seeds` indicate a relational or schema-managed persistence layer, though the specific database engine is not shown here.
   - `backend/src/db` is the backend-side access point to that persistence layer.
   - The repo also has a top-level `db/README.md`, suggesting database setup or conventions are documented separately.

9. **Infrastructure and local execution**
   - `docker-compose.yml`, `infrastructure/docker`, and `infrastructure/k8s` show support for both **local container composition** and **Kubernetes deployment**.
   - `run.bat` indicates Windows-friendly startup support.
   - `.env.example` suggests environment-driven configuration across components.

10. **Documentation and planning artifacts**
   - `docs/architecture/system_architecture.md` is the primary architecture documentation source in the repo.
   - `docs/prd/` and `deliverables/project_plan.md` show product and delivery planning materials alongside implementation code.
   - These are useful for understanding intended behavior, but the code layout itself already implies the runtime boundaries.

11. **Testing strategy**
   - `tests/agents`, `tests/backend`, and `tests/frontend` show test separation by subsystem.
   - `test_flow.py` suggests there is at least one higher-level end-to-end or workflow-oriented test that crosses boundaries.
   - This reinforces that the system is meant to be validated both per layer and as an integrated flow.

12. **Likely end-to-end flow**
   - A user interacts with the **frontend**.
   - The frontend calls the **backend** over HTTP and possibly sockets for live updates.
   - The backend invokes the **agent orchestration layer** to execute role-based workflows, possibly using graph/state logic and tools.
   - Results are persisted through the backend’s DB layer and rendered back in the frontend.

13. **How to draw the architecture**
   - Represent the system as three main boxes: **Frontend**, **Backend**, and **Agents/Workflow Engine**.
   - Add **Shared Schemas/Types** as a cross-cutting layer between them.
   - Add **Database**, **Uploads**, and **External LLM/tooling** as dependencies of the backend/agents side.
   - Show **Docker/K8s** as deployment infrastructure rather than application logic.

Main entry points: [`frontend/index.html`](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/frontend/index.html) (UI shell), [`agents/agents/graph.py`](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/agents/agents/graph.py) (Agent core), [`backend/app/main.py`](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/backend/app/main.py) (App entry), [`backend/src/services`](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/services) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agents"]
  node_agents_core{{"Agent core<br/>orchestrator<br/>[graph.py]"}}
  node_agents_roles["Role agents<br/>multi-agent"]
  node_agents_prompts["Prompts<br/>prompt templates"]
  node_agents_tools["Tools"]
  node_agents_state["State model<br/>workflow state<br/>[state.py]"]
end

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>service entry<br/>[main.py]"]
  node_backend_agent["Agent bridge<br/>integration<br/>[agent.py]"]
  node_backend_api["API layer<br/>http api"]
  node_backend_services["Services<br/>business logic"]
  node_backend_db["DB access<br/>persistence layer"]
  node_backend_sockets["Sockets<br/>realtime"]
  node_backend_langgraph{{"LangGraph<br/>workflow runtime"}}
  node_backend_uploads[("Uploads<br/>artifact storage")]
end

subgraph group_frontend["Frontend"]
  node_frontend_shell["UI shell<br/>frontend app<br/>[index.html]"]
  node_frontend_chat["Chat<br/>ui feature"]
  node_frontend_agents["Agent panel<br/>ui feature"]
  node_frontend_office["Office view<br/>ui feature"]
  node_frontend_store["Client store<br/>state"]
end

subgraph group_shared["Shared"]
  node_shared_contracts["Contracts<br/>shared schemas"]
end

subgraph group_data["Data"]
  node_data_migrations["Migrations<br/>schema assets"]
  node_data_seeds["Seeds<br/>data assets"]
end

subgraph group_platform["Platform"]
  node_infra_compose["Compose<br/>local deployment<br/>[docker-compose.yml]"]
  node_infra_k8s["K8s<br/>deployment manifests"]
  node_docs_arch["Architecture<br/>docs"]
  node_plan_doc["Plan<br/>[project_plan.md]"]
end

node_frontend_shell -->|"renders"| node_frontend_chat
node_frontend_shell -->|"renders"| node_frontend_agents
node_frontend_shell -->|"renders"| node_frontend_office
node_frontend_shell -->|"uses"| node_frontend_store
node_frontend_shell -->|"calls"| node_backend_api
node_frontend_shell -->|"streams"| node_backend_sockets
node_frontend_shell -->|"shares"| node_shared_contracts
node_backend_main -->|"serves"| node_backend_api
node_backend_main -->|"wires"| node_backend_agent
node_backend_api -->|"delegates"| node_backend_services
node_backend_services -->|"persists"| node_backend_db
node_backend_services -->|"stores"| node_backend_uploads
node_backend_api -->|"publishes"| node_backend_sockets
node_backend_agent -->|"executes"| node_backend_langgraph
node_backend_agent -->|"orchestrates"| node_agents_core
node_agents_core -->|"coordinates"| node_agents_roles
node_agents_core -->|"tracks"| node_agents_state
node_agents_core -->|"loads"| node_agents_prompts
node_agents_core -->|"invokes"| node_agents_tools
node_agents_core -->|"uses"| node_shared_contracts
node_backend_services -->|"uses"| node_shared_contracts
node_backend_db -->|"backed by"| node_data_migrations
node_backend_db -->|"initialized by"| node_data_seeds
node_backend_main -->|"deploys via"| node_infra_compose
node_backend_main -->|"deploys via"| node_infra_k8s
node_docs_arch -->|"documents"| node_shared_contracts
node_plan_doc -.->|"references"| node_docs_arch

click node_frontend_shell "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/frontend/index.html"
click node_frontend_chat "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/chat"
click node_frontend_agents "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/agents"
click node_frontend_office "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/office"
click node_frontend_store "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/store"
click node_backend_main "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/backend/app/main.py"
click node_backend_agent "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/backend/app/agent.py"
click node_backend_api "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/api"
click node_backend_services "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/services"
click node_backend_db "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/db"
click node_backend_sockets "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/sockets"
click node_backend_langgraph "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/langgraph/graph"
click node_backend_uploads "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/uploads"
click node_agents_core "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/agents/agents/graph.py"
click node_agents_roles "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/agents"
click node_agents_prompts "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/prompts"
click node_agents_tools "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/tools"
click node_agents_state "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/agents/agents/state.py"
click node_shared_contracts "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/shared"
click node_data_migrations "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/database/migrations"
click node_data_seeds "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/database/seeds"
click node_infra_compose "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/docker-compose.yml"
click node_infra_k8s "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/infrastructure/k8s"
click node_docs_arch "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/docs/architecture/system_architecture.md"
click node_plan_doc "https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/deliverables/project_plan.md"

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_agents_core,node_agents_roles,node_agents_prompts,node_agents_tools,node_agents_state toneBlue
class node_backend_main,node_backend_agent,node_backend_api,node_backend_services,node_backend_db,node_backend_sockets,node_backend_langgraph,node_backend_uploads toneAmber
class node_frontend_shell,node_frontend_chat,node_frontend_agents,node_frontend_office,node_frontend_store toneMint
class node_shared_contracts toneRose
class node_data_migrations,node_data_seeds toneIndigo
class node_infra_compose,node_infra_k8s,node_docs_arch,node_plan_doc toneTeal
```

## Components

### Agents

Multi-agent workflow engine and prompts

- [Agent core](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/agents/agents/graph.py): orchestrator · Stateful agent execution and coordination · `agents/agents/graph.py`
- [Role agents](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/agents): multi-agent · Director, PM, design, dev, QA, consultant, partner agents · `agents/agents`
- [Prompts](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/prompts): prompt templates · Role-specific prompt definitions · `agents/prompts`
- [Tools](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/agents/tools): execution tools · Linter and test runner actions · `agents/tools`
- [State model](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/agents/agents/state.py): workflow state · Agent state and parsing/generation helpers · `agents/agents/state.py`

### Backend

Python service boundary and integrations

- [App entry](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/backend/app/main.py): service entry · Backend application bootstrap · `backend/app/main.py`
- [Agent bridge](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/backend/app/agent.py): integration · Backend adapter for agent execution · `backend/app/agent.py`
- [API layer](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/api): http api · Request handlers and application endpoints · `backend/src/api`
- [Services](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/services): business logic · Backend domain and orchestration logic · `backend/src/services`
- [DB access](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/db): persistence layer · Backend-side data access boundary · `backend/src/db`
- [Sockets](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/src/sockets): realtime · Live update and streaming channel · `backend/src/sockets`
- [LangGraph](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/langgraph/graph): workflow runtime · Graph-based orchestration runtime integration · `backend/langgraph/graph`
- [Uploads](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/backend/uploads): artifact storage · File intake and workflow artifacts · `backend/uploads`

### Frontend

Browser UI and client state

- [UI shell](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/frontend/index.html): frontend app · Browser entry and top-level client app · `frontend/index.html`
- [Chat](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/chat): ui feature · Conversation-focused client components · `frontend/src/components/chat`
- [Agent panel](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/agents): ui feature · Agent visibility and control components · `frontend/src/components/agents`
- [Office view](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/components/office): ui feature · Workspace metaphor and scene components · `frontend/src/components/office`
- [Client store](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/frontend/src/store): state · Client-side state and hooks · `frontend/src/store`

### Shared

Cross-runtime contracts and types

- [Contracts](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/shared): shared schemas · Cross-runtime constants, schemas, and types · `shared`

### Data

Persistence assets and database setup

- [Migrations](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/database/migrations): schema assets · Database migration definitions · `database/migrations`
- [Seeds](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/database/seeds): data assets · Initial or sample database data · `database/seeds`

### Platform

Deployment and repo scaffolding

- [Compose](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/docker-compose.yml): local deployment · Container composition for local execution · `docker-compose.yml`
- [K8s](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/tree/main/infrastructure/k8s): deployment manifests · Kubernetes deployment scaffolding · `infrastructure/k8s`
- [Architecture](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/docs/architecture/system_architecture.md): docs · System architecture and design notes · `docs/architecture/system_architecture.md`
- [Plan](https://github.com/rahulbalhotra-ship-it/kpmg_ai_team/blob/main/deliverables/project_plan.md): planning · Project delivery and planning artifact · `deliverables/project_plan.md`

## Connections

- UI shell → Chat: renders · Shell hosts the main conversation surface
- UI shell → Agent panel: renders · Shell exposes agent controls and visibility
- UI shell → Office view: renders · Shell includes workspace-oriented views
- UI shell → Client store: uses · UI is backed by client state
- UI shell → API layer: calls · Browser UI talks to backend endpoints
- UI shell → Sockets: streams · Frontend receives live updates
- UI shell → Contracts: shares · Client aligns with shared types and schemas
- App entry → API layer: serves · Application entry wires API handlers
- App entry → Agent bridge: wires · Backend bootstraps agent integration
- API layer → Services: delegates · API layer calls business services
- Services → DB access: persists · Services use backend data access
- Services → Uploads: stores · Services manage workflow artifacts
- API layer → Sockets: publishes · API and services emit realtime events
- Agent bridge → LangGraph: executes · Backend agent bridge invokes graph runtime
- Agent bridge → Agent core: orchestrates · Backend dispatches work to agent engine
- Agent core → Role agents: coordinates · Core runtime sequences role-based agents
- Agent core → State model: tracks · Execution uses shared workflow state
- Agent core → Prompts: loads · Agent behavior is driven by prompts
- Agent core → Tools: invokes · Agents can run quality and test tools
- Agent core → Contracts: uses · Agent outputs follow shared schemas
- Services → Contracts: uses · Backend and client share domain contracts
- DB access → Migrations: backed by · Database layer depends on schema migrations
- DB access → Seeds: initialized by · Seed data supports local or test setup
- App entry → Compose: deploys via · Local runtime is composed with containers
- App entry → K8s: deploys via · Service is also prepared for Kubernetes
- Architecture → Contracts: documents · Architecture docs describe cross-runtime contracts
- Plan → Architecture: references · Delivery planning follows the architecture view