# shubham02022002/forge-studio architecture

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

- Interactive diagram: https://gitdiagram.com/shubham02022002/forge-studio
- Repository: https://github.com/shubham02022002/forge-studio

## Overview

Forge Studio turns a user’s written or spoken app idea into a clarified specification, blueprint, generated Vite/React project, and live browser preview. The main path runs through the workspace, same-origin API proxy, Express handlers, Groq-backed generation, and WebContainer sandbox; separate branches cover accounts, saved projects, export, and voice input. Source excerpts show key server calls, while the README documents the overall pipeline and proxy behavior; some web wiring and unsampled services are therefore represented only where documented.

Main entry points: [`apps/server/src/services/codegen.service.ts`](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/codegen.service.ts) (Code generation), [`apps/server/src/server.ts`](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/server.ts) (Express API), [`apps/server/src/config/db.ts`](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/config/db.ts) (PostgreSQL), [`apps/server/src/controllers/auth.controller.ts`](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/auth.controller.ts) (Auth handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_workspace["Workspace<br/>[workspace.tsx]"]
  node_voice_ui["Voice input<br/>[voice-input.tsx]"]
  node_projects_ui["Projects page<br/>[page.tsx]"]
  node_preview["Live preview<br/>[preview-pane.tsx]"]
  node_webcontainer["WebContainer<br/>[use-sandbox.ts]"]
  node_api_client["Web API client<br/>[api.ts]"]
  node_proxy["API proxy<br/>[route.ts]"]
end

subgraph group_api["API workflows"]
  node_server["Express API<br/>[server.ts]"]
  node_ai_routes["AI routes<br/>[ai.routes.ts]"]
  node_ai_controller["AI handlers<br/>[ai.controller.ts]"]
  node_voice_service["Voice transcription<br/>[voice.service.ts]"]
end

subgraph group_generation["Generation runtime"]
  node_groq["Groq models<br/>[groq.ts]"]
  node_ai_service["Clarify and blueprint<br/>[ai.service.ts]"]
  node_codegen["Code generation<br/>[codegen.service.ts]"]
  node_context["Edit context<br/>[context.service.ts]"]
  node_prompt["Generation prompts<br/>[codegen.prompt.ts]"]
  node_scaffold["Vite scaffold<br/>[scaffold.ts]"]
end

subgraph group_identity["Identity and projects"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_auth_controller["Auth handlers<br/>[auth.controller.ts]"]
  node_auth_service["Account service<br/>[auth.service.ts]"]
  node_session["Session service<br/>[session.service.ts]"]
  node_github["GitHub OAuth<br/>[github.service.ts]"]
  node_project_routes["Project routes<br/>[project.routes.ts]"]
  node_project_controller["Project handlers"]
  node_project_service["Project service<br/>[project.service.ts]"]
  node_export["ZIP export<br/>[export.service.ts]"]
  node_database[("PostgreSQL<br/>[db.ts]")]
end

node_user(("App builder"))

node_user -->|"describes app"| node_workspace
node_user -->|"speaks idea"| node_voice_ui
node_workspace -->|"requests generation"| node_api_client
node_api_client -->|"calls same origin"| node_proxy
node_proxy -->|"forwards requests"| node_server
node_server -->|"mounts routes"| node_ai_routes
node_ai_routes -->|"dispatches"| node_ai_controller
node_ai_controller -->|"clarifies and blueprints"| node_ai_service
node_ai_service -->|"calls models"| node_groq
node_ai_controller -->|"starts generation"| node_codegen
node_codegen -->|"streams completion"| node_groq
node_codegen -->|"builds edit context"| node_context
node_context -->|"selects relevant files"| node_groq
node_codegen -->|"builds prompts"| node_prompt
node_codegen -->|"assembles scaffold"| node_scaffold
node_codegen -->|"persists result"| node_database
node_codegen -->|"streams code events"| node_workspace
node_workspace -->|"shows generated app"| node_preview
node_preview -->|"runs project"| node_webcontainer
node_voice_ui -->|"submits audio"| node_server
node_server -->|"routes voice requests"| node_voice_service
node_server -->|"mounts routes"| node_auth_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"authenticates account"| node_auth_service
node_auth_controller -->|"creates session"| node_session
node_auth_controller -->|"completes OAuth"| node_github
node_auth_service -->|"reads and writes users"| node_database
node_session -->|"stores sessions"| node_database
node_server -->|"mounts routes"| node_project_routes
node_project_routes -->|"dispatches"| node_project_controller
node_project_controller -->|"manages projects"| node_project_service
node_project_controller -->|"exports project"| node_export
node_project_service -->|"reads and writes projects"| node_database
node_export -.->|"loads project files"| node_database
node_projects_ui -->|"loads saved projects"| node_api_client

click node_workspace "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/workspace.tsx"
click node_voice_ui "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/voice-input.tsx"
click node_projects_ui "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/app/(app)/projects/page.tsx"
click node_preview "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/preview-pane.tsx"
click node_webcontainer "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/hooks/use-sandbox.ts"
click node_api_client "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/lib/api.ts"
click node_proxy "https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/app/api/%5B...slug%5D/route.ts"
click node_server "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/server.ts"
click node_ai_routes "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/ai.routes.ts"
click node_ai_controller "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/ai.controller.ts"
click node_voice_service "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/voice.service.ts"
click node_groq "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/config/groq.ts"
click node_ai_service "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/ai.service.ts"
click node_codegen "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/codegen.service.ts"
click node_context "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/context.service.ts"
click node_prompt "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/prompts/codegen.prompt.ts"
click node_scaffold "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/templates/scaffold.ts"
click node_auth_routes "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/auth.routes.ts"
click node_auth_controller "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/auth.controller.ts"
click node_auth_service "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/auth.service.ts"
click node_session "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/session.service.ts"
click node_github "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/github.service.ts"
click node_project_routes "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/project.routes.ts"
click node_project_controller "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/project.controller.ts"
click node_project_service "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/project.service.ts"
click node_export "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/export.service.ts"
click node_database "https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/config/db.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_workspace,node_voice_ui,node_projects_ui,node_preview,node_webcontainer,node_api_client,node_proxy toneBlue
class node_server,node_ai_routes,node_ai_controller,node_voice_service toneAmber
class node_groq,node_ai_service,node_codegen,node_context,node_prompt,node_scaffold toneMint
class node_auth_routes,node_auth_controller,node_auth_service,node_session,node_github,node_project_routes,node_project_controller,node_project_service,node_export,node_database toneRose
class node_user toneIndigo
```

## Components

### Web experience

- [Workspace](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/workspace.tsx): `apps/web/src/components/workspace/workspace.tsx`
- [Voice input](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/voice-input.tsx): `apps/web/src/components/workspace/voice-input.tsx`
- [Projects page](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/app/(app)/projects/page.tsx): `apps/web/src/app/(app)/projects/page.tsx`
- [Live preview](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/components/workspace/preview-pane.tsx): `apps/web/src/components/workspace/preview-pane.tsx`
- [WebContainer](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/hooks/use-sandbox.ts): `apps/web/src/hooks/use-sandbox.ts`
- [Web API client](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [API proxy](https://github.com/shubham02022002/forge-studio/blob/main/apps/web/src/app/api/%5B...slug%5D/route.ts): `apps/web/src/app/api/[...slug]/route.ts`

### API workflows

- [Express API](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/server.ts): `apps/server/src/server.ts`
- [AI routes](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/ai.routes.ts): `apps/server/src/routes/ai.routes.ts`
- [AI handlers](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/ai.controller.ts): `apps/server/src/controllers/ai.controller.ts`
- [Voice transcription](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/voice.service.ts): `apps/server/src/services/voice.service.ts`

### Generation runtime

- [Groq models](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/config/groq.ts): `apps/server/src/config/groq.ts`
- [Clarify and blueprint](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/ai.service.ts): `apps/server/src/services/ai.service.ts`
- [Code generation](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/codegen.service.ts): `apps/server/src/services/codegen.service.ts`
- [Edit context](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/context.service.ts): `apps/server/src/services/context.service.ts`
- [Generation prompts](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/prompts/codegen.prompt.ts): `apps/server/src/prompts/codegen.prompt.ts`
- [Vite scaffold](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/templates/scaffold.ts): `apps/server/src/templates/scaffold.ts`

### Identity and projects

- [Auth routes](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/auth.routes.ts): `apps/server/src/routes/auth.routes.ts`
- [Auth handlers](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/auth.controller.ts): `apps/server/src/controllers/auth.controller.ts`
- [Account service](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/auth.service.ts): `apps/server/src/services/auth.service.ts`
- [Session service](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/session.service.ts): `apps/server/src/services/session.service.ts`
- [GitHub OAuth](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/github.service.ts): `apps/server/src/services/github.service.ts`
- [Project routes](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/routes/project.routes.ts): `apps/server/src/routes/project.routes.ts`
- [Project handlers](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/controllers/project.controller.ts): `apps/server/src/controllers/project.controller.ts`
- [Project service](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/project.service.ts): `apps/server/src/services/project.service.ts`
- [ZIP export](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/services/export.service.ts): `apps/server/src/services/export.service.ts`
- [PostgreSQL](https://github.com/shubham02022002/forge-studio/blob/main/apps/server/src/config/db.ts): `apps/server/src/config/db.ts`

### Other components

- **App builder**

## Connections

- App builder → Workspace: describes app
- App builder → Voice input: speaks idea
- Workspace → Web API client: requests generation
- Web API client → API proxy: calls same origin
- API proxy → Express API: forwards requests (evidence: `apps/web/src/app/api/[...slug]/route.ts`)
- Express API → AI routes: mounts routes (evidence: `apps/server/src/server.ts`)
- AI routes → AI handlers: dispatches (evidence: `apps/server/src/routes/ai.routes.ts`)
- AI handlers → Clarify and blueprint: clarifies and blueprints (evidence: `apps/server/src/controllers/ai.controller.ts`)
- Clarify and blueprint → Groq models: calls models (evidence: `apps/server/src/services/ai.service.ts`)
- AI handlers → Code generation: starts generation (evidence: `apps/server/src/controllers/ai.controller.ts`)
- Code generation → Groq models: streams completion (evidence: `apps/server/src/services/codegen.service.ts`)
- Code generation → Edit context: builds edit context (evidence: `apps/server/src/services/codegen.service.ts`)
- Edit context → Groq models: selects relevant files (evidence: `apps/server/src/services/context.service.ts`)
- Code generation → Generation prompts: builds prompts (evidence: `apps/server/src/services/codegen.service.ts`)
- Code generation → Vite scaffold: assembles scaffold (evidence: `apps/server/src/services/codegen.service.ts`)
- Code generation → PostgreSQL: persists result (evidence: `apps/server/src/services/codegen.service.ts`)
- Code generation → Workspace: streams code events
- Workspace → Live preview: shows generated app
- Live preview → WebContainer: runs project
- Voice input → Express API: submits audio
- Express API → Voice transcription: routes voice requests (evidence: `apps/server/src/server.ts`)
- Express API → Auth routes: mounts routes (evidence: `apps/server/src/server.ts`)
- Auth routes → Auth handlers: dispatches (evidence: `apps/server/src/routes/auth.routes.ts`)
- Auth handlers → Account service: authenticates account (evidence: `apps/server/src/controllers/auth.controller.ts`)
- Auth handlers → Session service: creates session (evidence: `apps/server/src/controllers/auth.controller.ts`)
- Auth handlers → GitHub OAuth: completes OAuth (evidence: `apps/server/src/controllers/auth.controller.ts`)
- Account service → PostgreSQL: reads and writes users (evidence: `apps/server/src/services/auth.service.ts`)
- Session service → PostgreSQL: stores sessions (evidence: `apps/server/src/services/session.service.ts`)
- Express API → Project routes: mounts routes (evidence: `apps/server/src/server.ts`)
- Project routes → Project handlers: dispatches (evidence: `apps/server/src/routes/project.routes.ts`)
- Project handlers → Project service: manages projects (evidence: `apps/server/src/controllers/project.controller.ts`)
- Project handlers → ZIP export: exports project (evidence: `apps/server/src/controllers/project.controller.ts`)
- Project service → PostgreSQL: reads and writes projects (evidence: `apps/server/src/services/project.service.ts`)
- ZIP export → PostgreSQL: loads project files
- Projects page → Web API client: loads saved projects
