# ansh-vaish/web-ide architecture

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

- Interactive diagram: https://gitdiagram.com/ansh-vaish/web-ide
- Repository: https://github.com/ansh-vaish/web-ide

## Overview

1. **Overall shape**
   - This is a Next.js App Router application with a clear split between public marketing/auth pages, a protected dashboard, and a per-playground editor runtime.
   - Most behavior is organized into feature modules under `modules/`, while `app/` primarily defines routes and layout boundaries.

2. **Routing and page boundaries**
   - `app/layout.tsx` and nested layouts establish the global shell, then route groups separate concerns:
     - `app/(home)` for the landing page
     - `app/(auth)` for sign-in
     - `app/dashboard` for authenticated project management
     - `app/playground/[id]` for the editor workspace
   - API routes live under `app/api`, including auth handlers and a template API.

3. **Authentication subsystem**
   - Auth is handled with NextAuth v5 (`auth.ts`, `auth.config.ts`) and Prisma-backed sessions/accounts.
   - OAuth providers are implemented in `lib/oauth/google.ts` and `lib/oauth/github.ts`.
   - The auth UI and helper logic live in `modules/auth`, including sign-in form, logout/user controls, and a current-user hook.
   - `middleware.ts` and `routes.ts` enforce public vs protected route behavior, redirecting unauthenticated users to sign-in.

4. **Persistence and server data model**
   - Prisma is the persistence layer (`prisma/schema.prisma`) and is configured for MongoDB.
   - `lib/db.ts` is the database access boundary used by server code/actions.
   - The README indicates the main persisted entities are users/auth records, playgrounds, serialized template/file-tree data, star marks, and chat messages.

5. **Dashboard subsystem**
   - `modules/dashboard` contains the authenticated project-management experience: project table, empty state, sidebar, add-new/add-repo entry points, star toggles, and a template-selection modal.
   - The dashboard page is the control center for creating, duplicating, updating, starring, and deleting playgrounds.
   - This layer is likely where server actions are triggered to create or mutate playground records before routing into the editor.

6. **Playground editor subsystem**
   - `app/playground/[id]` hosts the main coding workspace.
   - `modules/playground` contains the file explorer, editor, dialogs for file/folder CRUD, and loader states.
   - The playground feature is state-heavy and is separated into hooks (`usePlayground`, `useFileExplorer`) plus utility code for editor config and file-tree serialization.

7. **In-browser file system and editor state**
   - The playground maintains a serialized representation of the project tree and file contents, with operations for add/rename/delete, tab management, per-file save, and save-all.
   - `modules/playground/lib/path-to-json.ts` suggests conversion between a file-path structure and the JSON/tree model used in state and persistence.
   - This is the boundary where user edits in the Monaco editor are translated into app state and then into DB writes.

8. **Live execution and preview**
   - `modules/web-containers` wraps WebContainer-based runtime execution, including container bootstrapping, terminal UI, and preview rendering.
   - The container layer is isolated from the editor tree, which lets the app run project code in-browser without relying on a separate backend execution service.
   - A transformer hook suggests output/log stream adaptation between container events and the UI.

9. **Template and starter-project flow**
   - `app/api/template/[id]/route.ts` exposes template data to the app, and `lib/template.ts` likely centralizes template retrieval/normalization.
   - The large `starters-main/` directory contains starter projects for multiple frameworks/languages: Angular, Express, Hono, Next.js, React, and Vue.
   - These starters are the source material for new playgrounds and explain how the app can initialize different project shapes from templates.

10. **Shared UI and design system**
   - `components/ui` is a broad shared component library, likely generated around a design system such as shadcn/ui.
   - This folder provides the reusable primitives used by auth, dashboard, and playground screens, keeping those features visually consistent.
   - `lib/utils.ts` and `hooks/use-mobile.ts` support cross-cutting UI behavior.

11. **API surface**
   - The API surface is intentionally small: auth callbacks, error handling, and a template lookup endpoint.
   - Most feature mutations appear to be handled through server actions in `modules/*/actions`, rather than a large custom REST layer.
   - That means the main data flow is client interaction -> feature module action -> Prisma -> updated route/state.

12. **Deployment and environment**
   - The presence of `.github/workflows/deploy.yml` indicates CI/CD automation for deployment.
   - Runtime dependencies that materially affect architecture are Next.js/React, NextAuth, Prisma/MongoDB, Monaco Editor, and WebContainer; these define the app’s boundaries between server-rendered routing, persistent storage, and client-side execution.

Main entry points: [`lib/template.ts`](https://github.com/ansh-vaish/web-ide/blob/main/lib/template.ts) (Template library), [`app/layout.tsx`](https://github.com/ansh-vaish/web-ide/blob/main/app/layout.tsx) (Root layout), [`modules/playground`](https://github.com/ansh-vaish/web-ide/tree/main/modules/playground) (Playground module), [`components/ui`](https://github.com/ansh-vaish/web-ide/tree/main/components/ui) (UI system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_layout["Root layout<br/>next layout<br/>[layout.tsx]"]
  node_home_route["Home page<br/>marketing route<br/>[page.tsx]"]
  node_auth_route["Sign-in<br/>auth route<br/>[page.tsx]"]
  node_dashboard_route["Dashboard<br/>protected route<br/>[page.tsx]"]
  node_playground_route["Playground<br/>workspace route<br/>[page.tsx]"]
  node_api_auth["Auth API<br/>next api<br/>[route.ts]"]
  node_api_template["Template API<br/>next api<br/>[route.ts]"]
end

subgraph group_features["Feature modules"]
  node_auth_module["Auth module<br/>feature module"]
  node_dashboard_module["Dashboard module<br/>feature module"]
  node_playground_module["Playground module<br/>feature module"]
  node_webcontainers_module["WebContainer runtime<br/>runtime module"]
end

subgraph group_infra["Infra & data"]
  node_auth_core["Auth core<br/>nextauth config<br/>[auth.ts]"]
  node_oauth_providers["OAuth providers<br/>provider adapters<br/>[google.ts]"]
  node_db_layer[("Database layer<br/>prisma db<br/>[db.ts]")]
  node_template_lib["Template library<br/>template service<br/>[template.ts]"]
  node_middleware_routes["Route guard<br/>middleware<br/>[middleware.ts]"]
  node_ui_system["UI system<br/>shared components"]
end

subgraph group_starters["Starter projects"]
  node_starters_next["Next starter<br/>starter project"]
  node_starters_react["React starter<br/>starter project"]
  node_starters_vue["Vue starter<br/>starter project"]
  node_starters_express["Express starter<br/>starter project"]
  node_starters_hono["Hono starter<br/>starter project"]
end

node_app_layout -->|"renders"| node_home_route
node_app_layout -->|"renders"| node_auth_route
node_app_layout -->|"renders"| node_dashboard_route
node_app_layout -->|"renders"| node_playground_route
node_auth_route -->|"uses"| node_auth_module
node_dashboard_route -->|"uses"| node_dashboard_module
node_playground_route -->|"uses"| node_playground_module
node_playground_route -->|"embeds"| node_webcontainers_module
node_api_auth -->|"backs"| node_auth_core
node_auth_core -->|"loads"| node_oauth_providers
node_auth_core -->|"persists"| node_db_layer
node_middleware_routes -->|"redirects to"| node_auth_route
node_dashboard_module -->|"reads/writes"| node_db_layer
node_playground_module -->|"reads/writes"| node_db_layer
node_playground_module -->|"loads templates"| node_template_lib
node_api_template -->|"serves"| node_template_lib
node_template_lib -->|"sources"| node_starters_next
node_template_lib -->|"sources"| node_starters_react
node_template_lib -->|"sources"| node_starters_vue
node_template_lib -->|"sources"| node_starters_express
node_template_lib -->|"sources"| node_starters_hono
node_auth_module -->|"builds on"| node_ui_system
node_dashboard_module -->|"builds on"| node_ui_system
node_playground_module -->|"builds on"| node_ui_system
node_webcontainers_module -->|"builds on"| node_ui_system

click node_app_layout "https://github.com/ansh-vaish/web-ide/blob/main/app/layout.tsx"
click node_home_route "https://github.com/ansh-vaish/web-ide/blob/main/app/(home)/page.tsx"
click node_auth_route "https://github.com/ansh-vaish/web-ide/blob/main/app/(auth)/auth/sign-in/page.tsx"
click node_dashboard_route "https://github.com/ansh-vaish/web-ide/blob/main/app/dashboard/page.tsx"
click node_playground_route "https://github.com/ansh-vaish/web-ide/blob/main/app/playground/[id]/page.tsx"
click node_api_auth "https://github.com/ansh-vaish/web-ide/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_api_template "https://github.com/ansh-vaish/web-ide/blob/main/app/api/template/[id]/route.ts"
click node_auth_module "https://github.com/ansh-vaish/web-ide/tree/main/modules/auth"
click node_dashboard_module "https://github.com/ansh-vaish/web-ide/tree/main/modules/dashboard"
click node_playground_module "https://github.com/ansh-vaish/web-ide/tree/main/modules/playground"
click node_webcontainers_module "https://github.com/ansh-vaish/web-ide/tree/main/modules/web-containers"
click node_auth_core "https://github.com/ansh-vaish/web-ide/blob/main/auth.ts"
click node_oauth_providers "https://github.com/ansh-vaish/web-ide/blob/main/lib/oauth/google.ts"
click node_db_layer "https://github.com/ansh-vaish/web-ide/blob/main/lib/db.ts"
click node_template_lib "https://github.com/ansh-vaish/web-ide/blob/main/lib/template.ts"
click node_middleware_routes "https://github.com/ansh-vaish/web-ide/blob/main/middleware.ts"
click node_ui_system "https://github.com/ansh-vaish/web-ide/tree/main/components/ui"
click node_starters_next "https://github.com/ansh-vaish/web-ide/tree/main/starters-main/nextjs"
click node_starters_react "https://github.com/ansh-vaish/web-ide/tree/main/starters-main/react"
click node_starters_vue "https://github.com/ansh-vaish/web-ide/tree/main/starters-main/vue"
click node_starters_express "https://github.com/ansh-vaish/web-ide/tree/main/starters-main/express-simple"
click node_starters_hono "https://github.com/ansh-vaish/web-ide/tree/main/starters-main/hono-nodejs-starter"

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_layout,node_home_route,node_auth_route,node_dashboard_route,node_playground_route,node_api_auth,node_api_template toneBlue
class node_auth_module,node_dashboard_module,node_playground_module,node_webcontainers_module toneAmber
class node_auth_core,node_oauth_providers,node_db_layer,node_template_lib,node_middleware_routes,node_ui_system toneMint
class node_starters_next,node_starters_react,node_starters_vue,node_starters_express,node_starters_hono toneRose
```

## Components

### App Router

Route boundaries, layouts, and API endpoints.

- [Root layout](https://github.com/ansh-vaish/web-ide/blob/main/app/layout.tsx): next layout · Global app shell and shared styles. · `app/layout.tsx`
- [Home page](https://github.com/ansh-vaish/web-ide/blob/main/app/(home)/page.tsx): marketing route · Landing page route group. · `app/(home)/page.tsx`
- [Sign-in](https://github.com/ansh-vaish/web-ide/blob/main/app/(auth)/auth/sign-in/page.tsx): auth route · Public authentication page boundary. · `app/(auth)/auth/sign-in/page.tsx`
- [Dashboard](https://github.com/ansh-vaish/web-ide/blob/main/app/dashboard/page.tsx): protected route · Authenticated project-management entrypoint. · `app/dashboard/page.tsx`
- [Playground](https://github.com/ansh-vaish/web-ide/blob/main/app/playground/[id]/page.tsx): workspace route · Per-project editor workspace. · `app/playground/[id]/page.tsx`
- [Auth API](https://github.com/ansh-vaish/web-ide/blob/main/app/api/auth/[...nextauth]/route.ts): next api · NextAuth callback and session endpoints. · `app/api/auth/[...nextauth]/route.ts`
- [Template API](https://github.com/ansh-vaish/web-ide/blob/main/app/api/template/[id]/route.ts): next api · Template lookup endpoint for starters and playground creation. · `app/api/template/[id]/route.ts`

### Feature modules

Domain-specific UI, hooks, and actions.

- [Auth module](https://github.com/ansh-vaish/web-ide/tree/main/modules/auth): feature module · Sign-in form, user controls, logout, and current-user hook. · `modules/auth`
- [Dashboard module](https://github.com/ansh-vaish/web-ide/tree/main/modules/dashboard): feature module · Project table, actions, entry points, and template selection UI. · `modules/dashboard`
- [Playground module](https://github.com/ansh-vaish/web-ide/tree/main/modules/playground): feature module · Editor workspace, file explorer, dialogs, hooks, and save state. · `modules/playground`
- [WebContainer runtime](https://github.com/ansh-vaish/web-ide/tree/main/modules/web-containers): runtime module · Browser execution layer with terminal and preview. · `modules/web-containers`

### Infra & data

Auth, persistence, runtime integration, and templates.

- [Auth core](https://github.com/ansh-vaish/web-ide/blob/main/auth.ts): nextauth config · NextAuth configuration and auth entrypoint. · `auth.ts`
- [OAuth providers](https://github.com/ansh-vaish/web-ide/blob/main/lib/oauth/google.ts): provider adapters · Google and GitHub provider wiring. · `lib/oauth/google.ts`
- [Database layer](https://github.com/ansh-vaish/web-ide/blob/main/lib/db.ts): prisma db · Prisma access boundary and Mongo-backed schema. · `lib/db.ts`
- [Template library](https://github.com/ansh-vaish/web-ide/blob/main/lib/template.ts): template service · Template normalization and retrieval logic. · `lib/template.ts`
- [Route guard](https://github.com/ansh-vaish/web-ide/blob/main/middleware.ts): middleware · Public/protected route enforcement and redirects. · `middleware.ts`
- [UI system](https://github.com/ansh-vaish/web-ide/tree/main/components/ui): shared components · Reusable component primitives used across features. · `components/ui`

### Starter projects

Template source projects used to seed playgrounds.

- [Next starter](https://github.com/ansh-vaish/web-ide/tree/main/starters-main/nextjs): starter project · Reference starter for Next.js playgrounds. · `starters-main/nextjs`
- [React starter](https://github.com/ansh-vaish/web-ide/tree/main/starters-main/react): starter project · Reference starter for React playgrounds. · `starters-main/react`
- [Vue starter](https://github.com/ansh-vaish/web-ide/tree/main/starters-main/vue): starter project · Reference starter for Vue playgrounds. · `starters-main/vue`
- [Express starter](https://github.com/ansh-vaish/web-ide/tree/main/starters-main/express-simple): starter project · Reference starter for Express playgrounds. · `starters-main/express-simple`
- [Hono starter](https://github.com/ansh-vaish/web-ide/tree/main/starters-main/hono-nodejs-starter): starter project · Reference starter for Hono playgrounds. · `starters-main/hono-nodejs-starter`

## Connections

- Root layout → Home page: renders · Global shell wraps the public home route.
- Root layout → Sign-in: renders · Global shell wraps the auth route group.
- Root layout → Dashboard: renders · Global shell wraps authenticated pages.
- Root layout → Playground: renders · Global shell wraps the editor workspace.
- Sign-in → Auth module: uses · Sign-in page delegates to auth feature UI.
- Dashboard → Dashboard module: uses · Dashboard page is assembled from dashboard feature components.
- Playground → Playground module: uses · Workspace page delegates to the playground feature.
- Playground → WebContainer runtime: embeds · Workspace includes in-browser runtime and preview.
- Auth API → Auth core: backs · API route is driven by NextAuth config.
- Auth core → OAuth providers: loads · Auth config uses Google and GitHub providers.
- Auth core → Database layer: persists · Auth sessions and accounts are stored through Prisma.
- Route guard → Sign-in: redirects to · Unauthenticated users are sent to sign-in.
- Dashboard module → Database layer: reads/writes · Project management actions persist playground records.
- Playground module → Database layer: reads/writes · Editor state and saved files are persisted.
- Playground module → Template library: loads templates · Playground creation and starter hydration use template data.
- Template API → Template library: serves · Template endpoint exposes normalized starter data.
- Template library → Next starter: sources · Next.js starter material.
- Template library → React starter: sources · React starter material.
- Template library → Vue starter: sources · Vue starter material.
- Template library → Express starter: sources · Express starter material.
- Template library → Hono starter: sources · Hono starter material.
- Auth module → UI system: builds on · Auth UI uses shared primitives.
- Dashboard module → UI system: builds on · Dashboard UI uses shared primitives.
- Playground module → UI system: builds on · Editor UI uses shared primitives.
- WebContainer runtime → UI system: builds on · Terminal and preview use shared UI pieces.