# pierredelaguiche/moodle-app architecture

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

- Interactive diagram: https://gitdiagram.com/pierredelaguiche/moodle-app
- Repository: https://github.com/pierredelaguiche/moodle-app

## Overview

moodle-app is a local, read-only Moodle companion. Its main workflow is to configure a study folder and Moodle access, check courses and files, let the user choose downloads, organize and track those files locally, and optionally generate notes or ask questions with a chosen model. The browser UI also exposes deadlines, announcements, calendar, study, and activity features. The excerpts establish the HTTP/backend boundary and several service dependencies; relationships for unsampled features are included only where the README documents them.

Main entry points: [`src/moodle_app/web/app.py`](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/app.py) (App backend), [`src/moodle_app/llm/providers.py`](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/llm/providers.py) (Model providers), [`src/moodle_app/services/files.py`](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/files.py) (File tracking), [`src/moodle_app/moodle`](https://github.com/pierredelaguiche/moodle-app/tree/main/src/moodle_app/moodle) (Moodle service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface"]
  node_browser["Browser UI"]
  node_http["Local server<br/>[server.py]"]
  node_backend["App backend<br/>[app.py]"]
  node_jobs["Background jobs<br/>[jobs.py]"]
  node_dashboard["Dashboard and lists<br/>[digest.py]"]
  node_calendar["Calendar and deadlines<br/>[calendar.py]"]
  node_ical["Calendar feed<br/>[ics.py]"]
end

subgraph group_moodle["Moodle synchronization"]
  node_moodle["Moodle service"]
  node_sync["Course sync<br/>[sync.py]"]
  node_files["File tracking<br/>[files.py]"]
  node_layout["File layout<br/>[layout.py]"]
  node_weekrules["Week rules<br/>[weeks.py]"]
end

subgraph group_study["Study workspace"]
  node_tracker["Progress tracker<br/>[tracker.py]"]
  node_study["Study and editor<br/>[editor.py]"]
  node_notes["Notes generation<br/>[notes.py]"]
  node_planner["Notes planner<br/>[planner.py]"]
  node_extract["Text extraction<br/>[extract.py]"]
  node_assistant["AI assistant<br/>[ai.py]"]
  node_chat["Folder chat<br/>[chat.py]"]
end

subgraph group_support["Local data and integrations"]
  node_studyfolder["Study folder"]
  node_db[("SQLite records<br/>[repos.py]")]
  node_config["User settings<br/>[config.py]"]
  node_provider["Model providers<br/>[providers.py]"]
  node_usage[("Model usage<br/>[usage.py]")]
end

node_user(("Student"))
node_external_moodle{{"Moodle site"}}
node_external_model{{"Chosen model"}}

node_user -->|"uses"| node_browser
node_browser -->|"requests API"| node_http
node_http -->|"routes requests"| node_backend
node_backend -->|"starts jobs"| node_jobs
node_backend -->|"checks Moodle"| node_sync
node_sync -->|"fetches course data"| node_moodle
node_moodle -->|"reads courses"| node_external_moodle
node_sync -->|"reconciles files"| node_files
node_files -->|"downloads selected files"| node_moodle
node_moodle -->|"saves files"| node_studyfolder
node_files -->|"records file state"| node_db
node_files -->|"plans destinations"| node_layout
node_layout -->|"uses week folders"| node_weekrules
node_backend -->|"serves dashboard data"| node_dashboard
node_backend -->|"serves calendar data"| node_calendar
node_calendar -->|"offers calendar feed"| node_ical
node_backend -->|"serves progress"| node_tracker
node_backend -->|"serves file editing"| node_study
node_backend -->|"starts note creation"| node_notes
node_notes -->|"plans note jobs"| node_planner
node_planner -->|"extracts source text"| node_extract
node_planner -->|"generates notes"| node_provider
node_provider -->|"sends prompts"| node_external_model
node_backend -->|"answers context questions"| node_assistant
node_backend -->|"offers folder chat"| node_chat
node_assistant -->|"requests completion"| node_provider
node_chat -->|"requests completion"| node_provider
node_provider -->|"tracks usage"| node_usage
node_backend -->|"uses settings"| node_config

click node_browser "https://github.com/pierredelaguiche/moodle-app/tree/main/src/moodle_app/web/static"
click node_http "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/server.py"
click node_backend "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/app.py"
click node_jobs "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/jobs.py"
click node_moodle "https://github.com/pierredelaguiche/moodle-app/tree/main/src/moodle_app/moodle"
click node_sync "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/sync.py"
click node_files "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/files.py"
click node_layout "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/layout.py"
click node_weekrules "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/domain/weeks.py"
click node_db "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/db/repos.py"
click node_config "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/config.py"
click node_dashboard "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/digest.py"
click node_calendar "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/calendar.py"
click node_ical "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/ics.py"
click node_tracker "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/tracker.py"
click node_study "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/editor.py"
click node_notes "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/notes.py"
click node_planner "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/notes/planner.py"
click node_extract "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/notes/extract.py"
click node_assistant "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/ai.py"
click node_chat "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/chat.py"
click node_provider "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/llm/providers.py"
click node_usage "https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/usage.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_browser,node_http,node_backend,node_jobs,node_dashboard,node_calendar,node_ical toneBlue
class node_moodle,node_sync,node_files,node_layout,node_weekrules toneAmber
class node_tracker,node_study,node_notes,node_planner,node_extract,node_assistant,node_chat toneMint
class node_studyfolder,node_db,node_config,node_provider,node_usage toneRose
class node_user,node_external_moodle,node_external_model toneIndigo
```

## Components

### User interface

- [Browser UI](https://github.com/pierredelaguiche/moodle-app/tree/main/src/moodle_app/web/static): `src/moodle_app/web/static`
- [Local server](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/server.py): `src/moodle_app/web/server.py`
- [App backend](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/app.py): `src/moodle_app/web/app.py`
- [Background jobs](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/web/jobs.py): `src/moodle_app/web/jobs.py`
- [Dashboard and lists](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/digest.py): `src/moodle_app/services/digest.py`
- [Calendar and deadlines](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/calendar.py): `src/moodle_app/services/calendar.py`
- [Calendar feed](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/ics.py): `src/moodle_app/services/ics.py`

### Moodle synchronization

- [Moodle service](https://github.com/pierredelaguiche/moodle-app/tree/main/src/moodle_app/moodle): `src/moodle_app/moodle`
- [Course sync](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/sync.py): `src/moodle_app/services/sync.py`
- [File tracking](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/files.py): `src/moodle_app/services/files.py`
- [File layout](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/layout.py): `src/moodle_app/services/layout.py`
- [Week rules](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/domain/weeks.py): `src/moodle_app/domain/weeks.py`

### Study workspace

- [Progress tracker](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/tracker.py): `src/moodle_app/services/tracker.py`
- [Study and editor](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/editor.py): `src/moodle_app/services/editor.py`
- [Notes generation](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/notes.py): `src/moodle_app/services/notes.py`
- [Notes planner](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/notes/planner.py): `src/moodle_app/notes/planner.py`
- [Text extraction](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/notes/extract.py): `src/moodle_app/notes/extract.py`
- [AI assistant](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/ai.py): `src/moodle_app/services/ai.py`
- [Folder chat](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/chat.py): `src/moodle_app/services/chat.py`

### Local data and integrations

- **Study folder**
- [SQLite records](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/db/repos.py): `src/moodle_app/db/repos.py`
- [User settings](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/config.py): `src/moodle_app/config.py`
- [Model providers](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/llm/providers.py): `src/moodle_app/llm/providers.py`
- [Model usage](https://github.com/pierredelaguiche/moodle-app/blob/main/src/moodle_app/services/usage.py): `src/moodle_app/services/usage.py`

### Other components

- **Student**
- **Moodle site**
- **Chosen model**

## Connections

- Student → Browser UI: uses
- Browser UI → Local server: requests API (evidence: `src/moodle_app/web/server.py`)
- Local server → App backend: routes requests (evidence: `src/moodle_app/web/server.py`)
- App backend → Background jobs: starts jobs (evidence: `src/moodle_app/web/app.py`)
- App backend → Course sync: checks Moodle (evidence: `src/moodle_app/web/app.py`)
- Course sync → Moodle service: fetches course data (evidence: `src/moodle_app/services/sync.py`)
- Moodle service → Moodle site: reads courses
- Course sync → File tracking: reconciles files (evidence: `src/moodle_app/services/sync.py`)
- File tracking → Moodle service: downloads selected files (evidence: `src/moodle_app/services/files.py`)
- Moodle service → Study folder: saves files
- File tracking → SQLite records: records file state (evidence: `src/moodle_app/services/files.py`)
- File tracking → File layout: plans destinations (evidence: `src/moodle_app/services/files.py`)
- File layout → Week rules: uses week folders (evidence: `src/moodle_app/services/layout.py`)
- App backend → Dashboard and lists: serves dashboard data (evidence: `src/moodle_app/web/app.py`)
- App backend → Calendar and deadlines: serves calendar data (evidence: `src/moodle_app/web/server.py`)
- Calendar and deadlines → Calendar feed: offers calendar feed
- App backend → Progress tracker: serves progress (evidence: `src/moodle_app/web/app.py`)
- App backend → Study and editor: serves file editing (evidence: `src/moodle_app/web/server.py`)
- App backend → Notes generation: starts note creation
- Notes generation → Notes planner: plans note jobs (evidence: `src/moodle_app/services/notes.py`)
- Notes planner → Text extraction: extracts source text (evidence: `src/moodle_app/notes/planner.py`)
- Notes planner → Model providers: generates notes (evidence: `src/moodle_app/notes/planner.py`)
- Model providers → Chosen model: sends prompts (evidence: `src/moodle_app/llm/providers.py`)
- App backend → AI assistant: answers context questions (evidence: `src/moodle_app/web/app.py`)
- App backend → Folder chat: offers folder chat (evidence: `src/moodle_app/web/app.py`)
- AI assistant → Model providers: requests completion (evidence: `src/moodle_app/services/ai.py`)
- Folder chat → Model providers: requests completion (evidence: `src/moodle_app/services/chat.py`)
- Model providers → Model usage: tracks usage (evidence: `src/moodle_app/services/usage.py`)
- App backend → User settings: uses settings (evidence: `src/moodle_app/web/server.py`)
