# jay4ignite/liveclass architecture

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

- Interactive diagram: https://gitdiagram.com/jay4ignite/liveclass
- Repository: https://github.com/jay4ignite/liveclass

## Overview

LiveClass IDE is a bring-your-own-IDE classroom: an instructor shares project edits from VS Code, while students receive an authorized, versioned mirror and can reconnect to converge. The VS Code controller coordinates login, class/session controls, transport, and IDE adapters; the sync engine applies edits, and the WebSocket gateway authorizes, sequences, and relays them. The API handles identity and session lifecycle, with PostgreSQL for durable records and Redis for collaboration state. The web dashboard is explicitly a stub. Some backend links are grounded in the SOURCE INDEX rather than complete excerpts; unsampled details are not expanded.

Main entry points: [`services/collaboration/src/liveclass_collab/gateway.py`](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/gateway.py) (WebSocket gateway), [`extensions/vscode/src/controller.ts`](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/controller.ts) (VS Code controller), [`services/collaboration/src/liveclass_collab/app.py`](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/app.py) (ASGI app), [`services/api/src/liveclass_api/core/authz.py`](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/authz.py) (Authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ide["IDE clients"]
  node_controller["VS Code controller<br/>[controller.ts]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_connection["Reconnect manager"]
  node_ide_adapter["IDE mirrors<br/>[vscodeAdapter.ts]"]
  node_workspace["Workspace approval"]
  node_transport["WebSocket transport<br/>[wsTransport.ts]"]
end

subgraph group_sync["Protocol and sync"]
  node_engine["Sync engine<br/>[engine.ts]"]
  node_edit_ops["Edit operations<br/>[edits.ts]"]
  node_protocol["Wire protocol models<br/>[models.py]"]
  node_validators["TS validators<br/>[validators.ts]"]
end

subgraph group_api["HTTP API"]
  node_app["ASGI app<br/>[app.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_class_routes["Class routes<br/>[classes.py]"]
  node_session_routes["Session lifecycle<br/>[sessions.py]"]
  node_dependencies["Request dependencies<br/>[deps.py]"]
  node_authorization["Authorization<br/>[authz.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_db_session["Database access<br/>[db.py]"]
  node_models["Durable domain models<br/>[models.py]"]
  node_logging["Logging setup<br/>[logging.py]"]
end

subgraph group_collab["Collaboration backend"]
  node_gateway["WebSocket gateway<br/>[gateway.py]"]
  node_sequencer["Edit sequencer<br/>[sequencer.py]"]
  node_snapshots["Snapshot recovery<br/>[snapshots.py]"]
  node_presence["Presence tracking<br/>[presence.py]"]
  node_rate_limit["Message rate limits<br/>[ratelimit.py]"]
  node_redis_client["Collaboration Redis<br/>[redis_client.py]"]
end

subgraph group_web["Web dashboard"]
  node_web_app["Dashboard stub<br/>[App.tsx]"]
  node_web_api["Dashboard API calls<br/>[api.ts]"]
end

node_instructor(("Instructor"))
node_student(("Student"))
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_instructor -->|"operates"| node_controller
node_student -->|"joins through"| node_controller
node_controller -->|"calls"| node_api_client
node_controller -->|"starts"| node_connection
node_controller -->|"creates"| node_engine
node_controller -->|"provides"| node_transport
node_controller -->|"configures"| node_ide_adapter
node_ide_adapter -->|"uses"| node_workspace
node_engine -->|"registers callbacks"| node_transport
node_engine -->|"applies edits"| node_edit_ops
node_engine -->|"validates messages"| node_validators
node_web_app -->|"calls"| node_web_api
node_app -->|"configures"| node_logging
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_class_routes
node_app -->|"registers"| node_session_routes
node_app -->|"registers"| node_gateway
node_auth_routes -->|"authenticates through"| node_authorization
node_auth_routes -->|"issues token"| node_security
node_authorization -->|"queries"| node_models
node_authorization -->|"verifies password"| node_security
node_dependencies -->|"loads identity"| node_authorization
node_dependencies -->|"decodes token"| node_security
node_dependencies -->|"gets session"| node_db_session
node_session_routes -->|"checks access"| node_authorization
node_session_routes -->|"creates and updates"| node_models
node_session_routes -->|"publishes lifecycle events"| node_redis
node_models -->|"uses base"| node_db_session
node_db_session -->|"loads database settings"| node_config
node_security -->|"loads JWT settings"| node_config
node_gateway -->|"authorizes connections"| node_authorization
node_gateway -->|"loads session documents"| node_models
node_gateway -->|"verifies tokens"| node_security
node_gateway -->|"sequences edits"| node_sequencer
node_gateway -->|"recovers documents"| node_snapshots
node_gateway -->|"tracks participants"| node_presence
node_gateway -->|"limits messages"| node_rate_limit
node_gateway -->|"gets Redis"| node_redis_client
node_redis_client -->|"connects"| node_redis
node_sequencer -.->|"stores edit state"| node_redis
node_snapshots -.->|"persists checkpoints"| node_postgres
node_db_session -.->|"reads and writes"| node_postgres
node_api_client -.->|"uses HTTP API"| node_app
node_web_api -.->|"uses HTTP API"| node_app

click node_controller "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/controller.ts"
click node_api_client "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/apiClient.ts"
click node_connection "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/connectionManager.ts"
click node_ide_adapter "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/vscodeAdapter.ts"
click node_workspace "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/workspaceApproval.ts"
click node_transport "https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/wsTransport.ts"
click node_engine "https://github.com/jay4ignite/liveclass/blob/main/packages/sync-engine/src/engine.ts"
click node_edit_ops "https://github.com/jay4ignite/liveclass/blob/main/packages/sync-engine/src/edits.ts"
click node_protocol "https://github.com/jay4ignite/liveclass/blob/main/packages/protocol/src/liveclass_protocol/models.py"
click node_validators "https://github.com/jay4ignite/liveclass/blob/main/packages/shared-types/src/validators.ts"
click node_web_app "https://github.com/jay4ignite/liveclass/blob/main/apps/web/src/App.tsx"
click node_web_api "https://github.com/jay4ignite/liveclass/blob/main/apps/web/src/api.ts"
click node_app "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/app.py"
click node_auth_routes "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/auth.py"
click node_class_routes "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/classes.py"
click node_session_routes "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/sessions.py"
click node_dependencies "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/deps.py"
click node_authorization "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/authz.py"
click node_security "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/security.py"
click node_config "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/config.py"
click node_db_session "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/db.py"
click node_models "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/models.py"
click node_logging "https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/logging.py"
click node_gateway "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/gateway.py"
click node_sequencer "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/sequencer.py"
click node_snapshots "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/snapshots.py"
click node_presence "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/presence.py"
click node_rate_limit "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/ratelimit.py"
click node_redis_client "https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/redis_client.py"

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_controller,node_api_client,node_connection,node_ide_adapter,node_workspace,node_transport toneBlue
class node_engine,node_edit_ops,node_protocol,node_validators,node_postgres,node_redis toneAmber
class node_app,node_auth_routes,node_class_routes,node_session_routes,node_dependencies,node_authorization,node_security,node_config,node_db_session,node_models,node_logging toneMint
class node_gateway,node_sequencer,node_snapshots,node_presence,node_rate_limit,node_redis_client toneRose
class node_web_app,node_web_api,node_instructor,node_student toneIndigo
```

## Components

### IDE clients

- [VS Code controller](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/controller.ts): `extensions/vscode/src/controller.ts`
- [API client](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/apiClient.ts): `extensions/vscode/src/apiClient.ts`
- [Reconnect manager](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/connectionManager.ts): `extensions/vscode/src/connectionManager.ts`
- [IDE mirrors](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/vscodeAdapter.ts): `extensions/vscode/src/vscodeAdapter.ts`
- [Workspace approval](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/workspaceApproval.ts): `extensions/vscode/src/workspaceApproval.ts`
- [WebSocket transport](https://github.com/jay4ignite/liveclass/blob/main/extensions/vscode/src/wsTransport.ts): `extensions/vscode/src/wsTransport.ts`

### Protocol and sync

- [Sync engine](https://github.com/jay4ignite/liveclass/blob/main/packages/sync-engine/src/engine.ts): `packages/sync-engine/src/engine.ts`
- [Edit operations](https://github.com/jay4ignite/liveclass/blob/main/packages/sync-engine/src/edits.ts): `packages/sync-engine/src/edits.ts`
- [Wire protocol models](https://github.com/jay4ignite/liveclass/blob/main/packages/protocol/src/liveclass_protocol/models.py): `packages/protocol/src/liveclass_protocol/models.py`
- [TS validators](https://github.com/jay4ignite/liveclass/blob/main/packages/shared-types/src/validators.ts): `packages/shared-types/src/validators.ts`

### HTTP API

- [ASGI app](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/app.py): `services/collaboration/src/liveclass_collab/app.py`
- [Authentication routes](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/auth.py): `services/api/src/liveclass_api/http/auth.py`
- [Class routes](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/classes.py): `services/api/src/liveclass_api/http/classes.py`
- [Session lifecycle](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/sessions.py): `services/api/src/liveclass_api/http/sessions.py`
- [Request dependencies](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/http/deps.py): `services/api/src/liveclass_api/http/deps.py`
- [Authorization](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/authz.py): `services/api/src/liveclass_api/core/authz.py`
- [JWT and passwords](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/security.py): `services/api/src/liveclass_api/core/security.py`
- [Runtime configuration](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/config.py): `services/api/src/liveclass_api/core/config.py`
- [Database access](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/db.py): `services/api/src/liveclass_api/core/db.py`
- [Durable domain models](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/models.py): `services/api/src/liveclass_api/core/models.py`
- [Logging setup](https://github.com/jay4ignite/liveclass/blob/main/services/api/src/liveclass_api/core/logging.py): `services/api/src/liveclass_api/core/logging.py`

### Collaboration backend

- [WebSocket gateway](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/gateway.py): `services/collaboration/src/liveclass_collab/gateway.py`
- [Edit sequencer](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/sequencer.py): `services/collaboration/src/liveclass_collab/sequencer.py`
- [Snapshot recovery](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/snapshots.py): `services/collaboration/src/liveclass_collab/snapshots.py`
- [Presence tracking](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/presence.py): `services/collaboration/src/liveclass_collab/presence.py`
- [Message rate limits](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/ratelimit.py): `services/collaboration/src/liveclass_collab/ratelimit.py`
- [Collaboration Redis](https://github.com/jay4ignite/liveclass/blob/main/services/collaboration/src/liveclass_collab/redis_client.py): `services/collaboration/src/liveclass_collab/redis_client.py`

### Web dashboard

- [Dashboard stub](https://github.com/jay4ignite/liveclass/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Dashboard API calls](https://github.com/jay4ignite/liveclass/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### Other components

- **Instructor**
- **Student**
- **PostgreSQL**
- **Redis**

## Connections

- Instructor → VS Code controller: operates (evidence: `README.md`)
- Student → VS Code controller: joins through (evidence: `README.md`)
- VS Code controller → API client: calls (evidence: `extensions/vscode/src/controller.ts`)
- VS Code controller → Reconnect manager: starts (evidence: `extensions/vscode/src/controller.ts`)
- VS Code controller → Sync engine: creates (evidence: `extensions/vscode/src/controller.ts`)
- VS Code controller → WebSocket transport: provides (evidence: `extensions/vscode/src/controller.ts`)
- VS Code controller → IDE mirrors: configures (evidence: `extensions/vscode/src/controller.ts`)
- IDE mirrors → Workspace approval: uses (evidence: `extensions/vscode/src/workspaceApproval.ts`)
- Sync engine → WebSocket transport: registers callbacks (evidence: `packages/sync-engine/src/engine.ts`)
- Sync engine → Edit operations: applies edits (evidence: `packages/sync-engine/src/engine.ts`)
- Sync engine → TS validators: validates messages (evidence: `packages/sync-engine/src/engine.ts`)
- Dashboard stub → Dashboard API calls: calls (evidence: `apps/web/src/App.tsx`)
- ASGI app → Logging setup: configures (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → Authentication routes: registers (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → Class routes: registers (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → Session lifecycle: registers (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → WebSocket gateway: registers (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- Authentication routes → Authorization: authenticates through (evidence: `services/api/src/liveclass_api/http/auth.py`)
- Authentication routes → JWT and passwords: issues token (evidence: `services/api/src/liveclass_api/http/auth.py`)
- Authorization → Durable domain models: queries (evidence: `services/api/src/liveclass_api/core/authz.py`)
- Authorization → JWT and passwords: verifies password (evidence: `services/api/src/liveclass_api/core/authz.py`)
- Request dependencies → Authorization: loads identity (evidence: `services/api/src/liveclass_api/http/deps.py`)
- Request dependencies → JWT and passwords: decodes token (evidence: `services/api/src/liveclass_api/http/deps.py`)
- Request dependencies → Database access: gets session (evidence: `services/api/src/liveclass_api/http/deps.py`)
- Session lifecycle → Authorization: checks access (evidence: `services/api/src/liveclass_api/http/sessions.py`)
- Session lifecycle → Durable domain models: creates and updates (evidence: `services/api/src/liveclass_api/http/sessions.py`)
- Session lifecycle → Redis: publishes lifecycle events (evidence: `services/api/src/liveclass_api/http/sessions.py`)
- Durable domain models → Database access: uses base (evidence: `services/api/src/liveclass_api/core/models.py`)
- Database access → Runtime configuration: loads database settings (evidence: `services/api/src/liveclass_api/core/db.py`)
- JWT and passwords → Runtime configuration: loads JWT settings (evidence: `services/api/src/liveclass_api/core/security.py`)
- WebSocket gateway → Authorization: authorizes connections (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Durable domain models: loads session documents (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → JWT and passwords: verifies tokens (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Edit sequencer: sequences edits (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Snapshot recovery: recovers documents (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Presence tracking: tracks participants (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Message rate limits: limits messages (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Collaboration Redis: gets Redis (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- Collaboration Redis → Redis: connects (evidence: `services/collaboration/src/liveclass_collab/redis_client.py`)
- Edit sequencer → Redis: stores edit state
- Snapshot recovery → PostgreSQL: persists checkpoints
- Database access → PostgreSQL: reads and writes
- API client → ASGI app: uses HTTP API
- Dashboard API calls → ASGI app: uses HTTP API
