# lazyfetch/runtime architecture

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

- Interactive diagram: https://gitdiagram.com/lazyfetch/runtime
- Repository: https://github.com/lazyfetch/runtime

## Overview

Runtime is a browser-based, multi-language code execution platform. Users authenticate, open or save projects, edit code, execute it and view results or submission history; interactive programs can instead run in a live terminal session. The backend supports queued, cached execution and a direct-execution mode, with Docker isolation and PostgreSQL-backed user and project data. The graph combines sampled source with README-documented capabilities; unsampled internals are represented only where the tree supports a path, and uncertain wiring is omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/lazyfetch/runtime/blob/main/frontend/src/App.tsx) (Routes and session), [`frontend/src/pages/EditorPage.tsx`](https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/EditorPage.tsx) (Code editor), [`backend/src/main/java/com/runtime/service/ExecutionService.java`](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/ExecutionService.java) (Queue and cache), [`backend/src/main/java/com/runtime/engine/DockerExecutorUtil.java`](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/engine/DockerExecutorUtil.java) (Docker executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser app"]
  node_app["Routes and session<br/>[App.tsx]"]
  node_auth_pages["Login and signup<br/>[LoginPage.tsx]"]
  node_dashboard["Project dashboard<br/>[DashboardPage.tsx]"]
  node_editor["Code editor<br/>[EditorPage.tsx]"]
  node_auth_hook["Auth actions<br/>[useAuth.ts]"]
  node_execution_hook["Execution actions"]
  node_projects_hook["Project actions<br/>[useProjects.ts]"]
  node_submissions_hook["History actions"]
  node_auth_api["Auth API<br/>[auth.api.ts]"]
  node_execution_api["Execution API<br/>[execution.api.ts]"]
  node_projects_api["Projects API<br/>[projects.api.ts]"]
  node_submissions_api["Submissions API<br/>[submission.api.ts]"]
end

subgraph group_identity["Identity"]
  node_auth_controller["Auth endpoints"]
  node_auth_service["Credentials and tokens<br/>[AuthService.java]"]
  node_guest_service["Guest tokens"]
  node_oauth_handler["OAuth callback"]
  node_jwt["JWT utilities<br/>[JwtUtil.java]"]
end

subgraph group_execution["Code execution"]
  node_execution_controller["Execution endpoints"]
  node_execution_service["Queue and cache"]
  node_direct_controller["Direct execution"]
  node_job_producer["Job producer<br/>[JobProducer.java]"]
  node_job_consumer["Job worker<br/>[JobConsumer.java]"]
  node_docker_executor["Docker executor"]
  node_redis[("Queue and result cache")]
  node_docker["Isolated containers"]
end

subgraph group_interactive["Interactive terminal"]
  node_websocket_handler["Session handler"]
  node_terminal["Interactive terminal"]
end

subgraph group_records["Projects and history"]
  node_saved_controller["Project endpoints"]
  node_saved_service["Project management"]
  node_submission_controller["History endpoints"]
  node_submission_service["Submission records"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))
node_google["Google OAuth"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_auth_pages
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_editor
node_auth_pages -->|"invokes"| node_auth_hook
node_auth_hook -->|"calls"| node_auth_api
node_auth_api -->|"HTTP requests"| node_auth_controller
node_auth_controller -->|"delegates"| node_auth_service
node_auth_controller -->|"delegates"| node_guest_service
node_auth_service -->|"reads and writes users"| node_postgres
node_auth_service -->|"generates tokens"| node_jwt
node_guest_service -->|"writes guest user"| node_postgres
node_guest_service -->|"generates token"| node_jwt
node_google -.->|"OAuth identity"| node_oauth_handler
node_oauth_handler -.->|"reads and writes users"| node_postgres
node_oauth_handler -.->|"generates token"| node_jwt
node_dashboard -->|"loads projects"| node_projects_hook
node_projects_hook -->|"calls"| node_projects_api
node_projects_api -->|"HTTP requests"| node_saved_controller
node_saved_controller -->|"delegates"| node_saved_service
node_saved_service -->|"reads and writes projects"| node_postgres
node_editor -->|"runs code"| node_execution_hook
node_execution_hook -->|"calls"| node_execution_api
node_execution_api -->|"HTTP requests"| node_execution_controller
node_execution_controller -->|"delegates"| node_execution_service
node_execution_service -->|"checks cache and status"| node_redis
node_execution_service -->|"submits job"| node_job_producer
node_job_producer -->|"enqueues job"| node_redis
node_job_consumer -->|"dequeues job and stores result"| node_redis
node_job_consumer -->|"executes job"| node_docker_executor
node_docker_executor -->|"runs isolated code"| node_docker
node_job_consumer -->|"records execution"| node_submission_service
node_direct_controller -->|"executes code"| node_docker_executor
node_direct_controller -->|"records execution"| node_submission_service
node_execution_service -->|"returns job status"| node_execution_controller
node_editor -->|"opens session"| node_terminal
node_terminal -->|"WebSocket messages"| node_websocket_handler
node_websocket_handler -->|"starts interactive run"| node_docker_executor
node_websocket_handler -->|"streams container I/O"| node_docker
node_editor -->|"loads history"| node_submissions_hook
node_submissions_hook -->|"calls"| node_submissions_api
node_submissions_api -->|"HTTP requests"| node_submission_controller
node_submission_controller -->|"delegates"| node_submission_service
node_submission_service -->|"reads and writes submissions"| node_postgres

click node_app "https://github.com/lazyfetch/runtime/blob/main/frontend/src/App.tsx"
click node_auth_pages "https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_editor "https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/EditorPage.tsx"
click node_auth_hook "https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useAuth.ts"
click node_execution_hook "https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useCodeExecution.ts"
click node_projects_hook "https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useProjects.ts"
click node_submissions_hook "https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useSubmissionHistory.ts"
click node_auth_api "https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/auth.api.ts"
click node_execution_api "https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/execution.api.ts"
click node_projects_api "https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/projects.api.ts"
click node_submissions_api "https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/submission.api.ts"
click node_auth_controller "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/AuthController.java"
click node_auth_service "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/AuthService.java"
click node_guest_service "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/security/GuestTokenService.java"
click node_oauth_handler "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/security/OAuth2SuccessHandler.java"
click node_jwt "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/config/JwtUtil.java"
click node_execution_controller "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/ExecutionController.java"
click node_execution_service "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/ExecutionService.java"
click node_direct_controller "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/DirectExecutionController.java"
click node_job_producer "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/jobs/JobProducer.java"
click node_job_consumer "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/jobs/JobConsumer.java"
click node_docker_executor "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/engine/DockerExecutorUtil.java"
click node_websocket_handler "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/websocket/WebSocketHandler.java"
click node_terminal "https://github.com/lazyfetch/runtime/blob/main/frontend/src/components/terminal/InteractiveTerminal.tsx"
click node_saved_controller "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/SavedCodeController.java"
click node_saved_service "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/SavedCodeService.java"
click node_submission_controller "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/SubmissionController.java"
click node_submission_service "https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/SubmissionService.java"

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_auth_pages,node_dashboard,node_editor,node_auth_hook,node_execution_hook,node_projects_hook,node_submissions_hook,node_auth_api,node_execution_api,node_projects_api,node_submissions_api,node_user toneBlue
class node_auth_controller,node_auth_service,node_guest_service,node_oauth_handler,node_jwt toneAmber
class node_execution_controller,node_execution_service,node_direct_controller,node_job_producer,node_job_consumer,node_docker_executor,node_redis,node_docker toneMint
class node_websocket_handler,node_terminal toneRose
class node_saved_controller,node_saved_service,node_submission_controller,node_submission_service,node_postgres,node_google toneIndigo
```

## Components

### Browser app

- [Routes and session](https://github.com/lazyfetch/runtime/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login and signup](https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Project dashboard](https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Code editor](https://github.com/lazyfetch/runtime/blob/main/frontend/src/pages/EditorPage.tsx): `frontend/src/pages/EditorPage.tsx`
- [Auth actions](https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Execution actions](https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useCodeExecution.ts): `frontend/src/hooks/useCodeExecution.ts`
- [Project actions](https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useProjects.ts): `frontend/src/hooks/useProjects.ts`
- [History actions](https://github.com/lazyfetch/runtime/blob/main/frontend/src/hooks/useSubmissionHistory.ts): `frontend/src/hooks/useSubmissionHistory.ts`
- [Auth API](https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/auth.api.ts): `frontend/src/api/auth.api.ts`
- [Execution API](https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/execution.api.ts): `frontend/src/api/execution.api.ts`
- [Projects API](https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/projects.api.ts): `frontend/src/api/projects.api.ts`
- [Submissions API](https://github.com/lazyfetch/runtime/blob/main/frontend/src/api/submission.api.ts): `frontend/src/api/submission.api.ts`

### Identity

- [Auth endpoints](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/AuthController.java): `backend/src/main/java/com/runtime/controller/AuthController.java`
- [Credentials and tokens](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/AuthService.java): `backend/src/main/java/com/runtime/service/AuthService.java`
- [Guest tokens](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/security/GuestTokenService.java): `backend/src/main/java/com/runtime/security/GuestTokenService.java`
- [OAuth callback](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/security/OAuth2SuccessHandler.java): `backend/src/main/java/com/runtime/security/OAuth2SuccessHandler.java`
- [JWT utilities](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/config/JwtUtil.java): `backend/src/main/java/com/runtime/config/JwtUtil.java`

### Code execution

- [Execution endpoints](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/ExecutionController.java): `backend/src/main/java/com/runtime/controller/ExecutionController.java`
- [Queue and cache](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/ExecutionService.java): `backend/src/main/java/com/runtime/service/ExecutionService.java`
- [Direct execution](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/DirectExecutionController.java): `backend/src/main/java/com/runtime/controller/DirectExecutionController.java`
- [Job producer](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/jobs/JobProducer.java): `backend/src/main/java/com/runtime/jobs/JobProducer.java`
- [Job worker](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/jobs/JobConsumer.java): `backend/src/main/java/com/runtime/jobs/JobConsumer.java`
- [Docker executor](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/engine/DockerExecutorUtil.java): `backend/src/main/java/com/runtime/engine/DockerExecutorUtil.java`
- **Queue and result cache**
- **Isolated containers**

### Interactive terminal

- [Session handler](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/websocket/WebSocketHandler.java): `backend/src/main/java/com/runtime/websocket/WebSocketHandler.java`
- [Interactive terminal](https://github.com/lazyfetch/runtime/blob/main/frontend/src/components/terminal/InteractiveTerminal.tsx): `frontend/src/components/terminal/InteractiveTerminal.tsx`

### Projects and history

- [Project endpoints](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/SavedCodeController.java): `backend/src/main/java/com/runtime/controller/SavedCodeController.java`
- [Project management](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/SavedCodeService.java): `backend/src/main/java/com/runtime/service/SavedCodeService.java`
- [History endpoints](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/controller/SubmissionController.java): `backend/src/main/java/com/runtime/controller/SubmissionController.java`
- [Submission records](https://github.com/lazyfetch/runtime/blob/main/backend/src/main/java/com/runtime/service/SubmissionService.java): `backend/src/main/java/com/runtime/service/SubmissionService.java`
- **PostgreSQL**

### Other components

- **User**
- **Google OAuth**

## Connections

- User → Routes and session: uses
- Routes and session → Login and signup: routes to
- Routes and session → Project dashboard: routes to
- Routes and session → Code editor: routes to
- Login and signup → Auth actions: invokes
- Auth actions → Auth API: calls
- Auth API → Auth endpoints: HTTP requests
- Auth endpoints → Credentials and tokens: delegates
- Auth endpoints → Guest tokens: delegates
- Credentials and tokens → PostgreSQL: reads and writes users
- Credentials and tokens → JWT utilities: generates tokens
- Guest tokens → PostgreSQL: writes guest user
- Guest tokens → JWT utilities: generates token
- Google OAuth → OAuth callback: OAuth identity
- OAuth callback → PostgreSQL: reads and writes users
- OAuth callback → JWT utilities: generates token
- Project dashboard → Project actions: loads projects
- Project actions → Projects API: calls
- Projects API → Project endpoints: HTTP requests
- Project endpoints → Project management: delegates
- Project management → PostgreSQL: reads and writes projects
- Code editor → Execution actions: runs code
- Execution actions → Execution API: calls
- Execution API → Execution endpoints: HTTP requests
- Execution endpoints → Queue and cache: delegates
- Queue and cache → Queue and result cache: checks cache and status
- Queue and cache → Job producer: submits job
- Job producer → Queue and result cache: enqueues job
- Job worker → Queue and result cache: dequeues job and stores result
- Job worker → Docker executor: executes job
- Docker executor → Isolated containers: runs isolated code
- Job worker → Submission records: records execution
- Direct execution → Docker executor: executes code
- Direct execution → Submission records: records execution
- Queue and cache → Execution endpoints: returns job status
- Code editor → Interactive terminal: opens session
- Interactive terminal → Session handler: WebSocket messages
- Session handler → Docker executor: starts interactive run
- Session handler → Isolated containers: streams container I/O
- Code editor → History actions: loads history
- History actions → Submissions API: calls
- Submissions API → History endpoints: HTTP requests
- History endpoints → Submission records: delegates
- Submission records → PostgreSQL: reads and writes submissions