# sharveshc/codeflow architecture

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

- Interactive diagram: https://gitdiagram.com/sharveshc/codeflow
- Repository: https://github.com/sharveshc/codeflow

## Overview

#### Purpose and Entry Points
CodeFlow is a cloud coding environment: authenticated users edit, execute, organize, and AI-assist code snippets. The React/Vite client starts at `src/main.tsx`, composes routing and application shell in `src/App.tsx`, and exposes the primary workspace through `src/pages/Editor.tsx`.

#### Client Application and Routing
Page-level flows separate public landing/auth screens from the protected editor. Authentication state is provided globally, and access control gates editor routes.
- `src/App.tsx`
- `src/contexts/AuthContext.tsx`
- `src/components/ProtectedRoute.tsx`

#### Editor Workspace
The editor page coordinates code, language selection, execution, snippet selection, and editor preferences. Monaco-facing editing is isolated in the editor component; results are rendered separately in the output console.
- `src/pages/Editor.tsx`
- `src/components/EditorComponent.tsx`
- `src/components/OutputConsole.tsx`

#### Identity and User Boundary
Firebase Authentication supports email/password, Google sign-in, verification, and password-recovery views. The authenticated user identity is the boundary for private snippet ownership and protected navigation.
- `src/components/Auth.tsx`
- `src/pages/Login.tsx`
- `src/integrations/firebase/client.ts`

#### Snippet Persistence and Autosave
Snippet CRUD is centralized behind a client library and presented through the sidebar/list UI. Editor changes can be debounced and automatically persisted; duplicate handling and ownership safeguards belong to this persistence boundary. Firebase/Firestore rules and indexes are deployed alongside the application.
- `src/lib/snippets.ts`
- `src/components/SnippetList.tsx`
- `src/hooks/useAutoSave.ts`
- `firestore.rules`

#### Code Execution Boundary
Client code execution is delegated to an external Judge0 API, rather than running user code in the browser or repository infrastructure. The execution adapter handles submission/polling concerns and returns output for the workspace console.
- `src/lib/piston.ts`
- `src/pages/Editor.tsx`
- `src/components/OutputConsole.tsx`

#### AI Assistance Boundary
The chat widget sends requests to a configurable AI endpoint. A serverless handler protects the Google Generative AI key and brokers requests to Google’s model service; both root Vercel and alternate function-package layouts exist.
- `src/components/AIChatWidget.tsx`
- `api/ai-chat.js`
- `vercel-api/api/ai-chat.js`

#### Runtime and Deployment
The frontend is TypeScript/React 18 built by Vite, with Tailwind and shadcn/Radix-style UI components. Vercel is the intended production host for static delivery and serverless AI functions. Firebase supplies Authentication and Firestore; repository Firebase config also supports Firebase hosting/deployment artifacts.
- `package.json`
- `vercel.json`
- `firebase.json`

Main entry points: [`src/pages/Editor.tsx`](https://github.com/sharveshc/codeflow/blob/main/src/pages/Editor.tsx) (Editor workspace), [`src/App.tsx`](https://github.com/sharveshc/codeflow/blob/main/src/App.tsx) (App shell & routes), [`src/lib/snippets.ts`](https://github.com/sharveshc/codeflow/blob/main/src/lib/snippets.ts) (Snippet library), [`vercel.json`](https://github.com/sharveshc/codeflow/blob/main/vercel.json) (Vercel hosting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_entry["Client entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app["App shell &amp; routes<br/>React routing<br/>[App.tsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.tsx]"]
  node_protected_route["Route guard<br/>access control<br/>[ProtectedRoute.tsx]"]
  node_auth_ui["Authentication UI<br/>auth views<br/>[Auth.tsx]"]
  node_editor_page["Editor workspace<br/>workspace coordinator<br/>[Editor.tsx]"]
  node_code_editor["Code editor<br/>Monaco integration"]
  node_output_console["Output console<br/>result view<br/>[OutputConsole.tsx]"]
  node_snippet_list["Snippet sidebar<br/>snippet UI<br/>[SnippetList.tsx]"]
  node_autosave["Autosave<br/>debounced persistence<br/>[useAutoSave.ts]"]
  node_ai_widget["AI chat widget<br/>chat UI<br/>[AIChatWidget.tsx]"]
end

subgraph group_firebase["Firebase services"]
  node_snippet_store["Snippet library<br/>Firestore client adapter<br/>[snippets.ts]"]
  node_firebase_client["Firebase client<br/>Firebase integration<br/>[client.ts]"]
  node_firestore_rules["Firestore access rules<br/>security policy<br/>[firestore.rules]"]
  node_firebase_deployment["Firebase deployment config<br/>hosting artifacts<br/>[firebase.json]"]
end

subgraph group_external["External APIs"]
  node_execution_adapter["Judge0 adapter<br/>execution client<br/>[piston.ts]"]
  node_judge0{{"Judge0 API<br/>code execution service"}}
  node_google_ai{{"Google Generative AI<br/>model service"}}
end

subgraph group_deployment["Deployment"]
  node_ai_handler["AI serverless handler<br/>Vercel function<br/>[ai-chat.js]"]
  node_alternate_ai_handler["Alternate AI handler<br/>function-package layout<br/>[ai-chat.js]"]
  node_vercel{{"Vercel hosting<br/>static and serverless host<br/>[vercel.json]"}}
end

node_entry -->|"mounts"| node_app
node_app -->|"provides identity"| node_auth_context
node_app -->|"guards editor route"| node_protected_route
node_app -->|"public auth flow"| node_auth_ui
node_protected_route -->|"permits authenticated users"| node_editor_page
node_auth_context -->|"authenticates through"| node_firebase_client
node_auth_ui -->|"sign-in actions"| node_auth_context
node_editor_page -->|"edits code"| node_code_editor
node_editor_page -->|"displays results"| node_output_console
node_editor_page -->|"selects snippets"| node_snippet_list
node_editor_page -->|"persists changes"| node_autosave
node_snippet_list -->|"CRUD"| node_snippet_store
node_autosave -->|"debounced save"| node_snippet_store
node_snippet_store -->|"uses Firestore"| node_firebase_client
node_firestore_rules -.->|"authorizes ownership"| node_snippet_store
node_editor_page -->|"executes code"| node_execution_adapter
node_execution_adapter -->|"submission and polling"| node_judge0
node_execution_adapter -->|"returns output"| node_output_console
node_editor_page -->|"opens assistance"| node_ai_widget
node_ai_widget -->|"chat request"| node_ai_handler
node_ai_handler -->|"model request"| node_google_ai
node_alternate_ai_handler -.->|"alternate deployment path"| node_google_ai
node_vercel -->|"hosts function"| node_ai_handler
node_vercel -.->|"supports alternate layout"| node_alternate_ai_handler
node_vercel -->|"serves Vite build"| node_entry
node_firebase_deployment -.->|"deployment support"| node_firebase_client

click node_entry "https://github.com/sharveshc/codeflow/blob/main/src/main.tsx"
click node_app "https://github.com/sharveshc/codeflow/blob/main/src/App.tsx"
click node_auth_context "https://github.com/sharveshc/codeflow/blob/main/src/contexts/AuthContext.tsx"
click node_protected_route "https://github.com/sharveshc/codeflow/blob/main/src/components/ProtectedRoute.tsx"
click node_auth_ui "https://github.com/sharveshc/codeflow/blob/main/src/components/Auth.tsx"
click node_editor_page "https://github.com/sharveshc/codeflow/blob/main/src/pages/Editor.tsx"
click node_code_editor "https://github.com/sharveshc/codeflow/blob/main/src/components/EditorComponent.tsx"
click node_output_console "https://github.com/sharveshc/codeflow/blob/main/src/components/OutputConsole.tsx"
click node_snippet_list "https://github.com/sharveshc/codeflow/blob/main/src/components/SnippetList.tsx"
click node_autosave "https://github.com/sharveshc/codeflow/blob/main/src/hooks/useAutoSave.ts"
click node_snippet_store "https://github.com/sharveshc/codeflow/blob/main/src/lib/snippets.ts"
click node_firebase_client "https://github.com/sharveshc/codeflow/blob/main/src/integrations/firebase/client.ts"
click node_firestore_rules "https://github.com/sharveshc/codeflow/blob/main/firestore.rules"
click node_execution_adapter "https://github.com/sharveshc/codeflow/blob/main/src/lib/piston.ts"
click node_ai_widget "https://github.com/sharveshc/codeflow/blob/main/src/components/AIChatWidget.tsx"
click node_ai_handler "https://github.com/sharveshc/codeflow/blob/main/api/ai-chat.js"
click node_alternate_ai_handler "https://github.com/sharveshc/codeflow/blob/main/vercel-api/api/ai-chat.js"
click node_vercel "https://github.com/sharveshc/codeflow/blob/main/vercel.json"
click node_firebase_deployment "https://github.com/sharveshc/codeflow/blob/main/firebase.json"

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_entry,node_app,node_auth_context,node_protected_route,node_auth_ui,node_editor_page,node_code_editor,node_output_console,node_snippet_list,node_autosave,node_ai_widget toneBlue
class node_snippet_store,node_firebase_client,node_firestore_rules,node_firebase_deployment toneAmber
class node_execution_adapter,node_judge0,node_google_ai toneMint
class node_ai_handler,node_alternate_ai_handler,node_vercel toneRose
```

## Components

### React client

- [Client entry](https://github.com/sharveshc/codeflow/blob/main/src/main.tsx): React bootstrap · `src/main.tsx`
- [App shell & routes](https://github.com/sharveshc/codeflow/blob/main/src/App.tsx): React routing · Separates public auth pages from protected workspace routes. · `src/App.tsx`
- [Auth state](https://github.com/sharveshc/codeflow/blob/main/src/contexts/AuthContext.tsx): React context · `src/contexts/AuthContext.tsx`
- [Route guard](https://github.com/sharveshc/codeflow/blob/main/src/components/ProtectedRoute.tsx): access control · `src/components/ProtectedRoute.tsx`
- [Authentication UI](https://github.com/sharveshc/codeflow/blob/main/src/components/Auth.tsx): auth views · Email/password, Google sign-in, verification, and recovery flows. · `src/components/Auth.tsx`
- [Editor workspace](https://github.com/sharveshc/codeflow/blob/main/src/pages/Editor.tsx): workspace coordinator · Coordinates code, language, snippets, execution, and preferences. · `src/pages/Editor.tsx`
- [Code editor](https://github.com/sharveshc/codeflow/blob/main/src/components/EditorComponent.tsx): Monaco integration · `src/components/EditorComponent.tsx`
- [Output console](https://github.com/sharveshc/codeflow/blob/main/src/components/OutputConsole.tsx): result view · `src/components/OutputConsole.tsx`
- [Snippet sidebar](https://github.com/sharveshc/codeflow/blob/main/src/components/SnippetList.tsx): snippet UI · `src/components/SnippetList.tsx`
- [Autosave](https://github.com/sharveshc/codeflow/blob/main/src/hooks/useAutoSave.ts): debounced persistence · `src/hooks/useAutoSave.ts`
- [AI chat widget](https://github.com/sharveshc/codeflow/blob/main/src/components/AIChatWidget.tsx): chat UI · `src/components/AIChatWidget.tsx`

### Firebase services

- [Snippet library](https://github.com/sharveshc/codeflow/blob/main/src/lib/snippets.ts): Firestore client adapter · Centralizes CRUD, ownership safeguards, and duplicate handling. · `src/lib/snippets.ts`
- [Firebase client](https://github.com/sharveshc/codeflow/blob/main/src/integrations/firebase/client.ts): Firebase integration · Provides authenticated identity and Firestore access. · `src/integrations/firebase/client.ts`
- [Firestore access rules](https://github.com/sharveshc/codeflow/blob/main/firestore.rules): security policy · Enforces private snippet ownership. · `firestore.rules`
- [Firebase deployment config](https://github.com/sharveshc/codeflow/blob/main/firebase.json): hosting artifacts · `firebase.json`

### External APIs

- [Judge0 adapter](https://github.com/sharveshc/codeflow/blob/main/src/lib/piston.ts): execution client · Submits and polls external code execution. · `src/lib/piston.ts`
- **Judge0 API**: code execution service
- **Google Generative AI**: model service

### Deployment

- [AI serverless handler](https://github.com/sharveshc/codeflow/blob/main/api/ai-chat.js): Vercel function · Brokers requests while keeping the Google AI key server-side. · `api/ai-chat.js`
- [Alternate AI handler](https://github.com/sharveshc/codeflow/blob/main/vercel-api/api/ai-chat.js): function-package layout · Alternative serverless handler layout. · `vercel-api/api/ai-chat.js`
- [Vercel hosting](https://github.com/sharveshc/codeflow/blob/main/vercel.json): static and serverless host · `vercel.json`

## Connections

- Client entry → App shell & routes: mounts
- App shell & routes → Auth state: provides identity
- App shell & routes → Route guard: guards editor route
- App shell & routes → Authentication UI: public auth flow
- Route guard → Editor workspace: permits authenticated users
- Auth state → Firebase client: authenticates through
- Authentication UI → Auth state: sign-in actions
- Editor workspace → Code editor: edits code
- Editor workspace → Output console: displays results
- Editor workspace → Snippet sidebar: selects snippets
- Editor workspace → Autosave: persists changes
- Snippet sidebar → Snippet library: CRUD
- Autosave → Snippet library: debounced save
- Snippet library → Firebase client: uses Firestore
- Firestore access rules → Snippet library: authorizes ownership
- Editor workspace → Judge0 adapter: executes code
- Judge0 adapter → Judge0 API: submission and polling
- Judge0 adapter → Output console: returns output
- Editor workspace → AI chat widget: opens assistance
- AI chat widget → AI serverless handler: chat request
- AI serverless handler → Google Generative AI: model request
- Alternate AI handler → Google Generative AI: alternate deployment path
- Vercel hosting → AI serverless handler: hosts function
- Vercel hosting → Alternate AI handler: supports alternate layout
- Vercel hosting → Client entry: serves Vite build
- Firebase deployment config → Firebase client: deployment support