# ishanbhardwaj17/cloudforge architecture

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

- Interactive diagram: https://gitdiagram.com/ishanbhardwaj17/cloudforge
- Repository: https://github.com/ishanbhardwaj17/cloudforge

## Overview

CloudForge is a browser IDE backed by microservices. The main path is browser → sandbox control service → Kubernetes runtime, with the browser then using routed preview, file/terminal APIs, and AI-assisted edits. Auth and login notifications are separate supporting flows. The README documents lifecycle cleanup and several runtime integrations beyond the sampled code; those links are shown only where documented, with evidence limits noted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/App.jsx) (IDE Shell), [`sandbox/server/src/routes/sandbox.routes.js`](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/routes/sandbox.routes.js) (Sandbox API), [`sandbox/router/src/app.js`](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/router/src/app.js) (Sandbox Router), [`sandbox/agent/src/app.js`](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/agent/src/app.js) (Workspace Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ide["Browser IDE"]
  node_app["IDE Shell<br/>[App.jsx]"]
  node_launch["Sandbox Launch<br/>[SplashScreen.jsx]"]
  node_files_ui["File Explorer<br/>[FileExplorer.jsx]"]
  node_viewer["File Viewer<br/>[FileViewer.jsx]"]
  node_preview["Preview Frame<br/>[PreviewFrame.jsx]"]
  node_terminal_ui["Terminal UI<br/>[Terminal.jsx]"]
  node_ai_chat["AI Chat<br/>[AiChat.jsx]"]
  node_topbar["Workspace Bar<br/>[TopBar.jsx]"]
end

subgraph group_control["Sandbox Control"]
  node_sandbox_api["Sandbox API<br/>[sandbox.routes.js]"]
  node_projects[("Project Records<br/>[project.model.js]")]
  node_pod["Pod Provisioning<br/>[pod.js]"]
  node_service["Service Provisioning<br/>[service.js]"]
  node_ttl[("Sandbox TTL<br/>[redis.js]")]
end

subgraph group_runtime["Sandbox Runtime"]
  node_router["Sandbox Router<br/>[app.js]"]
  node_agent["Workspace Agent<br/>[app.js]"]
  node_template["Preview App<br/>[App.jsx]"]
  node_kubernetes["Kubernetes"]
  node_redis[("Redis")]
end

subgraph group_assistant["AI Assistant"]
  node_ai_api["AI API<br/>[agent.routes.js]"]
  node_code_agent["Code Agent<br/>[code.agent.js]"]
  node_agent_tools["Workspace Tools<br/>[tools.js]"]
end

subgraph group_identity["Identity &amp; Notifications"]
  node_auth_routes["Auth Routes<br/>[auth.routes.js]"]
  node_user_model[("User Records<br/>[user.model.js]")]
  node_rabbitmq["RabbitMQ"]
  node_notifications["Notification Consumer<br/>[app.js]"]
  node_email["Email Sender<br/>[email.js]"]
  node_mongo[("MongoDB")]
end

node_user(("Developer"))

node_user -->|"starts workspace"| node_launch
node_launch -->|"reports creation"| node_app
node_app -.->|"requests sandbox"| node_sandbox_api
node_sandbox_api -->|"creates pod"| node_pod
node_sandbox_api -->|"creates service"| node_service
node_sandbox_api -->|"creates TTL key"| node_ttl
node_sandbox_api -->|"reads/writes projects"| node_projects
node_pod -.->|"provisions runtime"| node_kubernetes
node_service -.->|"registers networking"| node_kubernetes
node_ttl -.->|"stores expiry"| node_redis
node_app -->|"renders"| node_files_ui
node_app -->|"renders"| node_viewer
node_app -->|"renders"| node_preview
node_app -->|"renders"| node_terminal_ui
node_app -->|"renders"| node_ai_chat
node_app -->|"renders"| node_topbar
node_app -->|"polls readiness"| node_sandbox_api
node_files_ui -.->|"lists files"| node_sandbox_api
node_viewer -.->|"reads file"| node_sandbox_api
node_terminal_ui -.->|"opens terminal channel"| node_router
node_preview -.->|"loads preview"| node_router
node_router -->|"refreshes TTL"| node_ttl
node_router -->|"proxies agent traffic"| node_agent
node_router -.->|"proxies preview traffic"| node_template
node_service -->|"routes agent port"| node_agent
node_service -.->|"routes preview port"| node_template
node_sandbox_api -->|"proxies file APIs"| node_agent
node_agent -.->|"serves workspace operations"| node_agent_tools
node_ai_chat -.->|"invokes assistant"| node_ai_api
node_ai_api -->|"streams agent"| node_code_agent
node_code_agent -->|"uses tools"| node_agent_tools
node_agent_tools -.->|"reads and updates files"| node_agent
node_user -.->|"authenticates"| node_auth_routes
node_auth_routes -->|"looks up/saves user"| node_user_model
node_user_model -.->|"persists users"| node_mongo
node_auth_routes -->|"publishes login event"| node_rabbitmq
node_rabbitmq -->|"delivers event"| node_notifications
node_notifications -->|"sends notification"| node_email

click node_app "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/App.jsx"
click node_launch "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/SplashScreen.jsx"
click node_files_ui "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/FileExplorer.jsx"
click node_viewer "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/FileViewer.jsx"
click node_preview "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/PreviewFrame.jsx"
click node_terminal_ui "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/Terminal.jsx"
click node_ai_chat "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/AiChat.jsx"
click node_topbar "https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/TopBar.jsx"
click node_sandbox_api "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/routes/sandbox.routes.js"
click node_projects "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/models/project.model.js"
click node_pod "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/kubernetes/pod.js"
click node_service "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/kubernetes/service.js"
click node_ttl "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/config/redis.js"
click node_router "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/router/src/app.js"
click node_agent "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/agent/src/app.js"
click node_template "https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/template/src/App.jsx"
click node_ai_api "https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/routes/agent.routes.js"
click node_code_agent "https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/agents/code.agent.js"
click node_agent_tools "https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/agents/tools.js"
click node_auth_routes "https://github.com/ishanbhardwaj17/cloudforge/blob/main/auth/src/routes/auth.routes.js"
click node_user_model "https://github.com/ishanbhardwaj17/cloudforge/blob/main/auth/src/models/user.model.js"
click node_notifications "https://github.com/ishanbhardwaj17/cloudforge/blob/main/notification/src/app.js"
click node_email "https://github.com/ishanbhardwaj17/cloudforge/blob/main/notification/src/email.js"

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_app,node_launch,node_files_ui,node_viewer,node_preview,node_terminal_ui,node_ai_chat,node_topbar toneBlue
class node_sandbox_api,node_projects,node_pod,node_service,node_ttl toneAmber
class node_router,node_agent,node_template,node_kubernetes,node_redis toneMint
class node_ai_api,node_code_agent,node_agent_tools toneRose
class node_auth_routes,node_user_model,node_rabbitmq,node_notifications,node_email,node_mongo,node_user toneIndigo
```

## Components

### Browser IDE

- [IDE Shell](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sandbox Launch](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/SplashScreen.jsx): `frontend/src/components/SplashScreen.jsx`
- [File Explorer](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/FileExplorer.jsx): `frontend/src/components/FileExplorer.jsx`
- [File Viewer](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/FileViewer.jsx): `frontend/src/components/FileViewer.jsx`
- [Preview Frame](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/PreviewFrame.jsx): `frontend/src/components/PreviewFrame.jsx`
- [Terminal UI](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/Terminal.jsx): `frontend/src/components/Terminal.jsx`
- [AI Chat](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/AiChat.jsx): `frontend/src/components/AiChat.jsx`
- [Workspace Bar](https://github.com/ishanbhardwaj17/cloudforge/blob/main/frontend/src/components/TopBar.jsx): `frontend/src/components/TopBar.jsx`

### Sandbox Control

- [Sandbox API](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/routes/sandbox.routes.js): `sandbox/server/src/routes/sandbox.routes.js`
- [Project Records](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/models/project.model.js): `sandbox/server/src/models/project.model.js`
- [Pod Provisioning](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/kubernetes/pod.js): `sandbox/server/src/kubernetes/pod.js`
- [Service Provisioning](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/kubernetes/service.js): `sandbox/server/src/kubernetes/service.js`
- [Sandbox TTL](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/server/src/config/redis.js): `sandbox/server/src/config/redis.js`

### Sandbox Runtime

- [Sandbox Router](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/router/src/app.js): `sandbox/router/src/app.js`
- [Workspace Agent](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/agent/src/app.js): `sandbox/agent/src/app.js`
- [Preview App](https://github.com/ishanbhardwaj17/cloudforge/blob/main/sandbox/template/src/App.jsx): `sandbox/template/src/App.jsx`
- **Kubernetes**
- **Redis**

### AI Assistant

- [AI API](https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/routes/agent.routes.js): `ai-orchestration/src/routes/agent.routes.js`
- [Code Agent](https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/agents/code.agent.js): `ai-orchestration/src/agents/code.agent.js`
- [Workspace Tools](https://github.com/ishanbhardwaj17/cloudforge/blob/main/ai-orchestration/src/agents/tools.js): `ai-orchestration/src/agents/tools.js`

### Identity & Notifications

- [Auth Routes](https://github.com/ishanbhardwaj17/cloudforge/blob/main/auth/src/routes/auth.routes.js): `auth/src/routes/auth.routes.js`
- [User Records](https://github.com/ishanbhardwaj17/cloudforge/blob/main/auth/src/models/user.model.js): `auth/src/models/user.model.js`
- **RabbitMQ**
- [Notification Consumer](https://github.com/ishanbhardwaj17/cloudforge/blob/main/notification/src/app.js): `notification/src/app.js`
- [Email Sender](https://github.com/ishanbhardwaj17/cloudforge/blob/main/notification/src/email.js): `notification/src/email.js`
- **MongoDB**

### Other components

- **Developer**

## Connections

- Developer → Sandbox Launch: starts workspace (evidence: `README.md`)
- Sandbox Launch → IDE Shell: reports creation (evidence: `frontend/src/App.jsx`)
- IDE Shell → Sandbox API: requests sandbox (evidence: `README.md`)
- Sandbox API → Pod Provisioning: creates pod (evidence: `sandbox/server/src/routes/sandbox.routes.js`)
- Sandbox API → Service Provisioning: creates service (evidence: `sandbox/server/src/routes/sandbox.routes.js`)
- Sandbox API → Sandbox TTL: creates TTL key (evidence: `sandbox/server/src/routes/sandbox.routes.js`)
- Sandbox API → Project Records: reads/writes projects (evidence: `sandbox/server/src/routes/sandbox.routes.js`)
- Pod Provisioning → Kubernetes: provisions runtime (evidence: `README.md`)
- Service Provisioning → Kubernetes: registers networking (evidence: `README.md`)
- Sandbox TTL → Redis: stores expiry (evidence: `README.md`)
- IDE Shell → File Explorer: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → File Viewer: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → Preview Frame: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → Terminal UI: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → AI Chat: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → Workspace Bar: renders (evidence: `frontend/src/App.jsx`)
- IDE Shell → Sandbox API: polls readiness (evidence: `frontend/src/App.jsx`)
- File Explorer → Sandbox API: lists files (evidence: `README.md`)
- File Viewer → Sandbox API: reads file (evidence: `README.md`)
- Terminal UI → Sandbox Router: opens terminal channel (evidence: `README.md`)
- Preview Frame → Sandbox Router: loads preview (evidence: `README.md`)
- Sandbox Router → Sandbox TTL: refreshes TTL (evidence: `sandbox/router/src/app.js`)
- Sandbox Router → Workspace Agent: proxies agent traffic (evidence: `sandbox/router/src/app.js`)
- Sandbox Router → Preview App: proxies preview traffic (evidence: `README.md`)
- Service Provisioning → Workspace Agent: routes agent port (evidence: `sandbox/server/src/kubernetes/service.js`)
- Service Provisioning → Preview App: routes preview port (evidence: `README.md`)
- Sandbox API → Workspace Agent: proxies file APIs
- Workspace Agent → Workspace Tools: serves workspace operations (evidence: `README.md`)
- AI Chat → AI API: invokes assistant (evidence: `README.md`)
- AI API → Code Agent: streams agent (evidence: `ai-orchestration/src/routes/agent.routes.js`)
- Code Agent → Workspace Tools: uses tools (evidence: `ai-orchestration/src/agents/code.agent.js`)
- Workspace Tools → Workspace Agent: reads and updates files (evidence: `README.md`)
- Developer → Auth Routes: authenticates (evidence: `README.md`)
- Auth Routes → User Records: looks up/saves user (evidence: `auth/src/routes/auth.routes.js`)
- User Records → MongoDB: persists users (evidence: `README.md`)
- Auth Routes → RabbitMQ: publishes login event (evidence: `auth/src/routes/auth.routes.js`)
- RabbitMQ → Notification Consumer: delivers event (evidence: `notification/src/app.js`)
- Notification Consumer → Email Sender: sends notification (evidence: `notification/src/app.js`)
