# jay4ignite/liveclass-ide architecture

> Architecture diagram of the GitHub repository jay4ignite/liveclass-ide, 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-ide
- Repository: https://github.com/jay4ignite/liveclass-ide

## Overview

LiveClass IDE is a teacher-led, real-time programming classroom: the teacher shares VS Code project edits, while students receive authorized read-only mirrors and reconnect by reconverging state. The walking-skeleton workflow runs from sign-in and session setup through WebSocket synchronization, server-side authorization and sequencing, then student workspace updates. The README also describes protocol packages and a stub dashboard; storage separates durable PostgreSQL records from ephemeral Redis collaboration state. Several important backend details are indexed but not excerpted, so their specific call relationships are omitted.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_vscode["VS Code extension<br/>[controller.ts]"]
  node_workspace["Workspace adapter<br/>[vscodeAdapter.ts]"]
  node_connection["Reconnect manager"]
  node_transport["WebSocket transport<br/>[wsTransport.ts]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_web["Dashboard stub<br/>[App.tsx]"]
end

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

subgraph group_backend["API and authorization"]
  node_app["ASGI app<br/>[app.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_session_routes["Session lifecycle<br/>[sessions.py]"]
  node_class_routes["Class routes<br/>[classes.py]"]
  node_authz["Identity and authorization<br/>[authz.py]"]
  node_security["Password and JWT<br/>[security.py]"]
  node_deps["HTTP auth dependencies<br/>[deps.py]"]
end

subgraph group_collab["Real-time collaboration"]
  node_gateway["WebSocket gateway<br/>[gateway.py]"]
  node_sequencer["Edit sequencer<br/>[sequencer.py]"]
  node_presence["Presence tracking<br/>[presence.py]"]
  node_snapshots["Snapshot recovery<br/>[snapshots.py]"]
  node_rate_limit["Connection rate limit<br/>[ratelimit.py]"]
end

subgraph group_state["Persistence"]
  node_pg[("PostgreSQL records<br/>[models.py]")]
  node_redis[("Redis state and pub/sub<br/>[redis_client.py]")]
end

node_teacher(("Teacher"))
node_student(("Student"))

node_teacher -->|"authors in"| node_vscode
node_student -->|"joins in"| node_vscode
node_vscode -->|"authenticates and manages sessions"| node_api_client
node_vscode -->|"creates"| node_sync_engine
node_vscode -->|"starts reconnects"| node_connection
node_vscode -->|"configures"| node_transport
node_vscode -->|"sets up sharing or mirroring"| node_workspace
node_web -->|"calls API"| node_api_client
node_sync_engine -->|"applies and normalizes"| node_edit_ops
node_sync_engine -->|"validates messages"| node_shared_types
node_sync_engine -.->|"sends and receives"| node_transport
node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_class_routes
node_app -->|"mounts"| node_session_routes
node_app -->|"mounts"| node_gateway
node_auth_routes -->|"authenticates user"| node_authz
node_auth_routes -->|"issues token"| node_security
node_authz -->|"verifies password"| node_security
node_deps -->|"verifies token"| node_security
node_deps -->|"loads user"| node_authz
node_authz -->|"queries identity and membership"| node_pg
node_session_routes -->|"publishes lifecycle events"| node_redis
node_session_routes -.->|"persists session state"| node_pg
node_gateway -->|"authorizes connection"| node_authz
node_gateway -->|"verifies token"| node_security
node_gateway -->|"parses messages"| node_protocol
node_gateway -->|"sequences edits"| node_sequencer
node_gateway -->|"tracks participants"| node_presence
node_gateway -->|"recovers document state"| node_snapshots
node_gateway -->|"limits inbound messages"| node_rate_limit
node_gateway -->|"publishes and subscribes"| node_redis
node_gateway -->|"loads session documents"| node_pg
node_sequencer -.->|"stores versioned operations"| node_redis
node_snapshots -.->|"persists checkpoints"| node_pg

click node_vscode "https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/controller.ts"
click node_workspace "https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/vscodeAdapter.ts"
click node_connection "https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/connectionManager.ts"
click node_transport "https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/wsTransport.ts"
click node_api_client "https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/apiClient.ts"
click node_web "https://github.com/jay4ignite/liveclass-ide/blob/main/apps/web/src/App.tsx"
click node_sync_engine "https://github.com/jay4ignite/liveclass-ide/blob/main/packages/sync-engine/src/engine.ts"
click node_edit_ops "https://github.com/jay4ignite/liveclass-ide/blob/main/packages/sync-engine/src/edits.ts"
click node_protocol "https://github.com/jay4ignite/liveclass-ide/blob/main/packages/protocol/src/liveclass_protocol/models.py"
click node_shared_types "https://github.com/jay4ignite/liveclass-ide/blob/main/packages/shared-types/src/validators.ts"
click node_app "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/app.py"
click node_auth_routes "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/auth.py"
click node_session_routes "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/sessions.py"
click node_class_routes "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/classes.py"
click node_authz "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/authz.py"
click node_security "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/security.py"
click node_deps "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/deps.py"
click node_gateway "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/gateway.py"
click node_sequencer "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/sequencer.py"
click node_presence "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/presence.py"
click node_snapshots "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/snapshots.py"
click node_rate_limit "https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/ratelimit.py"
click node_pg "https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/models.py"
click node_redis "https://github.com/jay4ignite/liveclass-ide/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_vscode,node_workspace,node_connection,node_transport,node_api_client,node_web toneBlue
class node_sync_engine,node_edit_ops,node_protocol,node_shared_types toneAmber
class node_app,node_auth_routes,node_session_routes,node_class_routes,node_authz,node_security,node_deps toneMint
class node_gateway,node_sequencer,node_presence,node_snapshots,node_rate_limit toneRose
class node_pg,node_redis,node_teacher,node_student toneIndigo
```

## Components

### Client applications

- [VS Code extension](https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/controller.ts): `extensions/vscode/src/controller.ts`
- [Workspace adapter](https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/vscodeAdapter.ts): `extensions/vscode/src/vscodeAdapter.ts`
- [Reconnect manager](https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/connectionManager.ts): `extensions/vscode/src/connectionManager.ts`
- [WebSocket transport](https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/wsTransport.ts): `extensions/vscode/src/wsTransport.ts`
- [API client](https://github.com/jay4ignite/liveclass-ide/blob/main/extensions/vscode/src/apiClient.ts): `extensions/vscode/src/apiClient.ts`
- [Dashboard stub](https://github.com/jay4ignite/liveclass-ide/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`

### Protocol and sync

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

### API and authorization

- [ASGI app](https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/app.py): `services/collaboration/src/liveclass_collab/app.py`
- [Authentication routes](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/auth.py): `services/api/src/liveclass_api/http/auth.py`
- [Session lifecycle](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/sessions.py): `services/api/src/liveclass_api/http/sessions.py`
- [Class routes](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/classes.py): `services/api/src/liveclass_api/http/classes.py`
- [Identity and authorization](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/authz.py): `services/api/src/liveclass_api/core/authz.py`
- [Password and JWT](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/security.py): `services/api/src/liveclass_api/core/security.py`
- [HTTP auth dependencies](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/http/deps.py): `services/api/src/liveclass_api/http/deps.py`

### Real-time collaboration

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

### Persistence

- [PostgreSQL records](https://github.com/jay4ignite/liveclass-ide/blob/main/services/api/src/liveclass_api/core/models.py): `services/api/src/liveclass_api/core/models.py`
- [Redis state and pub/sub](https://github.com/jay4ignite/liveclass-ide/blob/main/services/collaboration/src/liveclass_collab/redis_client.py): `services/collaboration/src/liveclass_collab/redis_client.py`

### Other components

- **Teacher**
- **Student**

## Connections

- Teacher → VS Code extension: authors in
- Student → VS Code extension: joins in
- VS Code extension → API client: authenticates and manages sessions (evidence: `extensions/vscode/src/controller.ts`)
- VS Code extension → Sync engine: creates (evidence: `extensions/vscode/src/controller.ts`)
- VS Code extension → Reconnect manager: starts reconnects (evidence: `extensions/vscode/src/controller.ts`)
- VS Code extension → WebSocket transport: configures (evidence: `extensions/vscode/src/controller.ts`)
- VS Code extension → Workspace adapter: sets up sharing or mirroring (evidence: `extensions/vscode/src/controller.ts`)
- Dashboard stub → API client: calls API (evidence: `apps/web/src/App.tsx`)
- Sync engine → Edit operations: applies and normalizes (evidence: `packages/sync-engine/src/engine.ts`)
- Sync engine → Shared TS validators: validates messages (evidence: `packages/sync-engine/src/engine.ts`)
- Sync engine → WebSocket transport: sends and receives
- ASGI app → Authentication routes: mounts (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → Class routes: mounts (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → Session lifecycle: mounts (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- ASGI app → WebSocket gateway: mounts (evidence: `services/collaboration/src/liveclass_collab/app.py`)
- Authentication routes → Identity and authorization: authenticates user (evidence: `services/api/src/liveclass_api/http/auth.py`)
- Authentication routes → Password and JWT: issues token (evidence: `services/api/src/liveclass_api/http/auth.py`)
- Identity and authorization → Password and JWT: verifies password (evidence: `services/api/src/liveclass_api/core/authz.py`)
- HTTP auth dependencies → Password and JWT: verifies token (evidence: `services/api/src/liveclass_api/http/deps.py`)
- HTTP auth dependencies → Identity and authorization: loads user (evidence: `services/api/src/liveclass_api/http/deps.py`)
- Identity and authorization → PostgreSQL records: queries identity and membership (evidence: `services/api/src/liveclass_api/core/authz.py`)
- Session lifecycle → Redis state and pub/sub: publishes lifecycle events (evidence: `services/api/src/liveclass_api/http/sessions.py`)
- Session lifecycle → PostgreSQL records: persists session state (evidence: `services/api/src/liveclass_api/http/sessions.py`)
- WebSocket gateway → Identity and authorization: authorizes connection (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Password and JWT: verifies token (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Wire protocol models: parses messages (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Edit sequencer: sequences edits (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Presence tracking: tracks participants (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Snapshot recovery: recovers document state (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Connection rate limit: limits inbound messages (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → Redis state and pub/sub: publishes and subscribes (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- WebSocket gateway → PostgreSQL records: loads session documents (evidence: `services/collaboration/src/liveclass_collab/gateway.py`)
- Edit sequencer → Redis state and pub/sub: stores versioned operations
- Snapshot recovery → PostgreSQL records: persists checkpoints (evidence: `services/collaboration/src/liveclass_collab/snapshots.py`)
