# harshit-rv/forge architecture

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

- Interactive diagram: https://gitdiagram.com/harshit-rv/forge
- Repository: https://github.com/harshit-rv/forge

## Overview

Forge is an AI website builder: a user submits an idea in the project chat, an agent edits and runs the app in a project-specific Kubernetes sandbox, and the user watches streamed activity and a live preview. The graph follows the documented workflow and sampled wiring; some API route-to-service and agent-to-sandbox details are not shown in the excerpts, so those links are omitted where unverified.

Main entry points: [`frontend/app/projects/[projectId]/page.tsx`](https://github.com/harshit-rv/forge/blob/main/frontend/app/projects/%5BprojectId%5D/page.tsx) (Forge web app), [`api/src/routes/projects.route.ts`](https://github.com/harshit-rv/forge/blob/main/api/src/routes/projects.route.ts) (Project routes), [`api/src/services/project.service.ts`](https://github.com/harshit-rv/forge/blob/main/api/src/services/project.service.ts) (Project service), [`api/src/services/message.service.ts`](https://github.com/harshit-rv/forge/blob/main/api/src/services/message.service.ts) (Message service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_web["Forge web app<br/>[page.tsx]"]
  node_chat["Chat workspace<br/>[chat-panel.tsx]"]
  node_workspace["Code workspace<br/>[workspace.tsx]"]
  node_preview["Live preview<br/>[preview-panel.tsx]"]
end

subgraph group_api["API"]
  node_apiapp["API server<br/>[app.ts]"]
  node_routes["Project routes<br/>[projects.route.ts]"]
  node_runservice["Agent run service<br/>[index.ts]"]
  node_projectservice["Project service<br/>[project.service.ts]"]
  node_messageservice["Message service<br/>[message.service.ts]"]
  node_projectstore[("Project records<br/>[Project.model.ts]")]
  node_messagestore[("Message records<br/>[Message.model.ts]")]
  node_sandboxadapter["Sandbox adapter<br/>[index.ts]"]
end

subgraph group_agent["Agent"]
  node_agent["AI agent<br/>[run-agent.ts]"]
  node_agenttools["Agent tools<br/>[tools.ts]"]
end

subgraph group_sandbox["Sandbox runtime"]
  node_sandboxlib["Sandbox lifecycle<br/>[sandbox.ts]"]
  node_workspaceops["Workspace operations<br/>[index.ts]"]
end

subgraph group_cluster["Kubernetes"]
  node_pod["Project pod<br/>[pod.ts]"]
  node_kubeservice["Preview service<br/>[service.ts]"]
end

node_user(("User"))
node_kubeapi["Kubernetes API"]
node_mongodb[("MongoDB")]
node_llm["Language model"]
node_browser(("Preview browser"))

node_user -->|"uses"| node_web
node_web -->|"shows chat"| node_chat
node_chat -->|"sends prompts"| node_apiapp
node_web -->|"opens project"| node_workspace
node_web -->|"shows preview"| node_preview
node_apiapp -->|"dispatches"| node_routes
node_routes -->|"starts runs"| node_runservice
node_routes -->|"manages projects"| node_projectservice
node_routes -->|"handles messages"| node_messageservice
node_projectservice -->|"reads/writes"| node_projectstore
node_messageservice -->|"checks ownership"| node_projectservice
node_messageservice -->|"reads/writes"| node_messagestore
node_projectservice -->|"starts/stops"| node_sandboxlib
node_sandboxadapter -->|"operates workspace"| node_workspaceops
node_sandboxlib -->|"provisions"| node_pod
node_sandboxlib -->|"manages service"| node_kubeservice
node_pod -->|"creates pod"| node_kubeapi
node_kubeservice -->|"creates service"| node_kubeapi
node_preview -->|"renders URL"| node_browser
node_browser -.->|"loads preview"| node_kubeservice

click node_web "https://github.com/harshit-rv/forge/blob/main/frontend/app/projects/%5BprojectId%5D/page.tsx"
click node_chat "https://github.com/harshit-rv/forge/blob/main/frontend/components/chat/chat-panel.tsx"
click node_workspace "https://github.com/harshit-rv/forge/blob/main/frontend/components/workspace/workspace.tsx"
click node_preview "https://github.com/harshit-rv/forge/blob/main/frontend/components/preview/preview-panel.tsx"
click node_apiapp "https://github.com/harshit-rv/forge/blob/main/api/src/app.ts"
click node_routes "https://github.com/harshit-rv/forge/blob/main/api/src/routes/projects.route.ts"
click node_runservice "https://github.com/harshit-rv/forge/blob/main/api/src/services/agent-run/index.ts"
click node_projectservice "https://github.com/harshit-rv/forge/blob/main/api/src/services/project.service.ts"
click node_messageservice "https://github.com/harshit-rv/forge/blob/main/api/src/services/message.service.ts"
click node_projectstore "https://github.com/harshit-rv/forge/blob/main/api/src/models/Project.model.ts"
click node_messagestore "https://github.com/harshit-rv/forge/blob/main/api/src/models/message/Message.model.ts"
click node_agent "https://github.com/harshit-rv/forge/blob/main/agent/src/run-agent.ts"
click node_agenttools "https://github.com/harshit-rv/forge/blob/main/agent/src/tools/tools.ts"
click node_sandboxadapter "https://github.com/harshit-rv/forge/blob/main/api/src/adapters/sandbox/index.ts"
click node_sandboxlib "https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/sandbox.ts"
click node_workspaceops "https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/workspace/index.ts"
click node_pod "https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/kube/pod.ts"
click node_kubeservice "https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/kube/service.ts"

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_web,node_chat,node_workspace,node_preview,node_user,node_browser toneBlue
class node_apiapp,node_routes,node_runservice,node_projectservice,node_messageservice,node_projectstore,node_messagestore,node_sandboxadapter,node_mongodb toneAmber
class node_agent,node_agenttools,node_kubeapi toneMint
class node_sandboxlib,node_workspaceops toneRose
class node_pod,node_kubeservice,node_llm toneIndigo
```

## Components

### Frontend

- [Forge web app](https://github.com/harshit-rv/forge/blob/main/frontend/app/projects/%5BprojectId%5D/page.tsx): `frontend/app/projects/[projectId]/page.tsx`
- [Chat workspace](https://github.com/harshit-rv/forge/blob/main/frontend/components/chat/chat-panel.tsx): `frontend/components/chat/chat-panel.tsx`
- [Code workspace](https://github.com/harshit-rv/forge/blob/main/frontend/components/workspace/workspace.tsx): `frontend/components/workspace/workspace.tsx`
- [Live preview](https://github.com/harshit-rv/forge/blob/main/frontend/components/preview/preview-panel.tsx): `frontend/components/preview/preview-panel.tsx`

### API

- [API server](https://github.com/harshit-rv/forge/blob/main/api/src/app.ts): `api/src/app.ts`
- [Project routes](https://github.com/harshit-rv/forge/blob/main/api/src/routes/projects.route.ts): `api/src/routes/projects.route.ts`
- [Agent run service](https://github.com/harshit-rv/forge/blob/main/api/src/services/agent-run/index.ts): `api/src/services/agent-run/index.ts`
- [Project service](https://github.com/harshit-rv/forge/blob/main/api/src/services/project.service.ts): `api/src/services/project.service.ts`
- [Message service](https://github.com/harshit-rv/forge/blob/main/api/src/services/message.service.ts): `api/src/services/message.service.ts`
- [Project records](https://github.com/harshit-rv/forge/blob/main/api/src/models/Project.model.ts): `api/src/models/Project.model.ts`
- [Message records](https://github.com/harshit-rv/forge/blob/main/api/src/models/message/Message.model.ts): `api/src/models/message/Message.model.ts`
- [Sandbox adapter](https://github.com/harshit-rv/forge/blob/main/api/src/adapters/sandbox/index.ts): `api/src/adapters/sandbox/index.ts`

### Agent

- [AI agent](https://github.com/harshit-rv/forge/blob/main/agent/src/run-agent.ts): `agent/src/run-agent.ts`
- [Agent tools](https://github.com/harshit-rv/forge/blob/main/agent/src/tools/tools.ts): `agent/src/tools/tools.ts`

### Sandbox runtime

- [Sandbox lifecycle](https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/sandbox.ts): `k8s-sandbox/src/sandbox.ts`
- [Workspace operations](https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/workspace/index.ts): `k8s-sandbox/src/workspace/index.ts`

### Kubernetes

- [Project pod](https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/kube/pod.ts): `k8s-sandbox/src/kube/pod.ts`
- [Preview service](https://github.com/harshit-rv/forge/blob/main/k8s-sandbox/src/kube/service.ts): `k8s-sandbox/src/kube/service.ts`

### Other components

- **User**
- **Kubernetes API**
- **MongoDB**
- **Language model**
- **Preview browser**

## Connections

- User → Forge web app: uses
- Forge web app → Chat workspace: shows chat
- Chat workspace → API server: sends prompts
- Forge web app → Code workspace: opens project
- Forge web app → Live preview: shows preview
- API server → Project routes: dispatches
- Project routes → Agent run service: starts runs
- Project routes → Project service: manages projects
- Project routes → Message service: handles messages
- Project service → Project records: reads/writes
- Message service → Project service: checks ownership
- Message service → Message records: reads/writes
- Project service → Sandbox lifecycle: starts/stops
- Sandbox adapter → Workspace operations: operates workspace
- Sandbox lifecycle → Project pod: provisions
- Sandbox lifecycle → Preview service: manages service
- Project pod → Kubernetes API: creates pod
- Preview service → Kubernetes API: creates service
- Live preview → Preview browser: renders URL
- Preview browser → Preview service: loads preview