# a27497/lecturelens architecture

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

- Interactive diagram: https://gitdiagram.com/a27497/lecturelens
- Repository: https://github.com/a27497/lecturelens

## Overview

LectureLens turns course video into searchable, time-linked learning material and supports a study loop from evidence-grounded questions through practice and feedback. The graph combines the documented Vue/Java/Python architecture with sampled agent modules; Java course services are represented as external because their source is not in the supplied tree. Several product capabilities are documented but their implementation was not sampled, so their internal connections are omitted.

Main entry points: [`frontend/src/App.vue`](https://github.com/a27497/lecturelens/blob/main/frontend/src/App.vue) (Vue workspace), [`agent-service/src/lecturelens_agent/study/runtime.py`](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/runtime.py) (Study runtime), [`agent-service/src/lecturelens_agent/app.py`](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/app.py) (Agent API), [`agent-service/src/lecturelens_agent/retrieval.py`](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/retrieval.py) (Evidence retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Learning workspace"]
  node_web["Vue workspace<br/>[App.vue]"]
  node_upload["Video upload"]
end

subgraph group_course["Course evidence"]
  node_course_service["Course services"]
  node_authority["Evidence authority<br/>[authority.py]"]
  node_retrieval["Evidence retrieval<br/>[retrieval.py]"]
  node_embedding["Embedding<br/>[embedding.py]"]
  node_evidence_index[("Evidence index<br/>[store.py]")]
end

subgraph group_agent["Study agent"]
  node_agent_api["Agent API<br/>[app.py]"]
  node_contracts["Agent contracts<br/>[contracts.py]"]
  node_study_runtime["Study runtime<br/>[runtime.py]"]
  node_provider["Model provider<br/>[provider.py]"]
  node_study_contracts["Study contracts<br/>[contracts.py]"]
  node_quality_review["Support review<br/>[support_review.py]"]
end

subgraph group_learning["Learning records"]
  node_study_store[("Run journal<br/>[store.py]")]
  node_study_features["Practice and review"]
end

subgraph group_tutor["Tutor experiments"]
  node_tutor_api["Tutor API<br/>[app.py]"]
  node_tutor_store[("Tutor records<br/>[store.py]")]
end

node_learner(("Learner"))
node_model["LLM service"]

node_learner -->|"uses"| node_web
node_web -->|"uploads video"| node_upload
node_upload -->|"submits media"| node_course_service
node_course_service -.->|"authorizes evidence"| node_authority
node_web -->|"asks questions"| node_agent_api
node_agent_api -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"embeds queries"| node_embedding
node_retrieval -.->|"searches index"| node_evidence_index
node_agent_api -->|"validates requests"| node_contracts
node_agent_api -->|"starts runs"| node_study_runtime
node_study_runtime -->|"builds decisions"| node_study_contracts
node_study_runtime -->|"requests decisions"| node_provider
node_provider -.->|"calls model"| node_model
node_study_runtime -->|"reviews candidates"| node_quality_review
node_study_runtime -.->|"journals runs"| node_study_store
node_study_store -->|"dispatches operations"| node_study_features
node_web -->|"continues practice"| node_study_features
node_web -.->|"opens Tutor"| node_tutor_api
node_tutor_api -->|"persists dialogue"| node_tutor_store
node_tutor_api -->|"checks course access"| node_authority

click node_web "https://github.com/a27497/lecturelens/blob/main/frontend/src/App.vue"
click node_upload "https://github.com/a27497/lecturelens/blob/main/frontend/src/components/upload/UploadFilePicker.vue"
click node_authority "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/authority.py"
click node_agent_api "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/app.py"
click node_retrieval "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/retrieval.py"
click node_embedding "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/embedding.py"
click node_evidence_index "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/store.py"
click node_contracts "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/contracts.py"
click node_study_runtime "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/runtime.py"
click node_provider "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/provider.py"
click node_study_contracts "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/contracts.py"
click node_quality_review "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/support_review.py"
click node_study_store "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/store.py"
click node_study_features "https://github.com/a27497/lecturelens/tree/main/agent-service/src/lecturelens_agent/study"
click node_tutor_api "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_real_eval/tutor/app.py"
click node_tutor_store "https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_real_eval/tutor/store.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_web,node_upload toneBlue
class node_course_service,node_authority,node_retrieval,node_embedding,node_evidence_index toneAmber
class node_agent_api,node_contracts,node_study_runtime,node_provider,node_study_contracts,node_quality_review toneMint
class node_study_store,node_study_features toneRose
class node_tutor_api,node_tutor_store,node_learner,node_model toneIndigo
```

## Components

### Learning workspace

- [Vue workspace](https://github.com/a27497/lecturelens/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Video upload](https://github.com/a27497/lecturelens/blob/main/frontend/src/components/upload/UploadFilePicker.vue): `frontend/src/components/upload/UploadFilePicker.vue`

### Course evidence

- **Course services**
- [Evidence authority](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/authority.py): `agent-service/src/lecturelens_agent/study/authority.py`
- [Evidence retrieval](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/retrieval.py): `agent-service/src/lecturelens_agent/retrieval.py`
- [Embedding](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/embedding.py): `agent-service/src/lecturelens_agent/embedding.py`
- [Evidence index](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/store.py): `agent-service/src/lecturelens_agent/store.py`

### Study agent

- [Agent API](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/app.py): `agent-service/src/lecturelens_agent/app.py`
- [Agent contracts](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/contracts.py): `agent-service/src/lecturelens_agent/contracts.py`
- [Study runtime](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/runtime.py): `agent-service/src/lecturelens_agent/study/runtime.py`
- [Model provider](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/provider.py): `agent-service/src/lecturelens_agent/study/provider.py`
- [Study contracts](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/contracts.py): `agent-service/src/lecturelens_agent/study/contracts.py`
- [Support review](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/support_review.py): `agent-service/src/lecturelens_agent/study/support_review.py`

### Learning records

- [Run journal](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_agent/study/store.py): `agent-service/src/lecturelens_agent/study/store.py`
- [Practice and review](https://github.com/a27497/lecturelens/tree/main/agent-service/src/lecturelens_agent/study): `agent-service/src/lecturelens_agent/study`

### Tutor experiments

- [Tutor API](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_real_eval/tutor/app.py): `agent-service/src/lecturelens_real_eval/tutor/app.py`
- [Tutor records](https://github.com/a27497/lecturelens/blob/main/agent-service/src/lecturelens_real_eval/tutor/store.py): `agent-service/src/lecturelens_real_eval/tutor/store.py`

### Other components

- **Learner**
- **LLM service**

## Connections

- Learner → Vue workspace: uses (evidence: `README.md`)
- Vue workspace → Video upload: uploads video (evidence: `README.md`)
- Video upload → Course services: submits media (evidence: `README.md`)
- Course services → Evidence authority: authorizes evidence
- Vue workspace → Agent API: asks questions (evidence: `README.md`)
- Agent API → Evidence retrieval: retrieves evidence (evidence: `agent-service/src/lecturelens_agent/app.py`)
- Evidence retrieval → Embedding: embeds queries (evidence: `agent-service/src/lecturelens_agent/retrieval.py`)
- Evidence retrieval → Evidence index: searches index
- Agent API → Agent contracts: validates requests (evidence: `agent-service/src/lecturelens_agent/app.py`)
- Agent API → Study runtime: starts runs (evidence: `agent-service/src/lecturelens_agent/app.py`)
- Study runtime → Study contracts: builds decisions (evidence: `agent-service/src/lecturelens_agent/study/runtime.py`)
- Study runtime → Model provider: requests decisions (evidence: `agent-service/src/lecturelens_agent/study/runtime.py`)
- Model provider → LLM service: calls model
- Study runtime → Support review: reviews candidates (evidence: `agent-service/src/lecturelens_agent/study/runtime.py`)
- Study runtime → Run journal: journals runs (evidence: `agent-service/src/lecturelens_agent/study/runtime.py`)
- Run journal → Practice and review: dispatches operations (evidence: `agent-service/src/lecturelens_agent/study/store.py`)
- Vue workspace → Practice and review: continues practice (evidence: `README.md`)
- Vue workspace → Tutor API: opens Tutor (evidence: `README.md`)
- Tutor API → Tutor records: persists dialogue (evidence: `agent-service/src/lecturelens_real_eval/tutor/app.py`)
- Tutor API → Evidence authority: checks course access (evidence: `agent-service/src/lecturelens_real_eval/tutor/app.py`)