# aarguellocedeno/agli architecture

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

- Interactive diagram: https://gitdiagram.com/aarguellocedeno/agli
- Repository: https://github.com/aarguellocedeno/agli

## Overview

AGLI is a Flask-based adaptive, gamified biology practice app. A learner signs in, receives a question, submits an answer, and sees feedback and progress; the practice service coordinates the adaptive engine, question bank, and persisted learner state. The engine combines BKT knowledge tracking, IRT ability/item estimates, contextual-bandit selection, and gamification. The tree also shows calibration and simulation tooling, but those are offline workflows rather than part of the learner-facing runtime. The README supplied no content, so connections for unsampled capabilities are omitted unless the source index or excerpts support them.

Main entry points: [`agli/servicios/juego.py`](https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/juego.py) (Practice coordinator), [`agli/agli_engine/engine.py`](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/engine.py) (Adaptive engine), [`agli/app.py`](https://github.com/aarguellocedeno/agli/blob/main/agli/app.py) (Flask app), [`agli/models.py`](https://github.com/aarguellocedeno/agli/blob/main/agli/models.py) (Data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Flask app<br/>[app.py]"]
  node_pages["Practice pages"]
  node_config["App configuration<br/>[config.py]"]
end

subgraph group_practice["Practice services"]
  node_game["Practice coordinator<br/>[juego.py]"]
  node_bank["Question bank<br/>[banco.py]"]
  node_badges["Badge rules<br/>[insignias.py]"]
end

subgraph group_adaptive["Adaptive engine"]
  node_engine["Adaptive engine<br/>[engine.py]"]
  node_bkt["Knowledge tracking<br/>[bkt_module.py]"]
  node_irt["IRT estimation<br/>[irt_module.py]"]
  node_bandit["LinUCB selection<br/>[bandit_module.py]"]
  node_gamification["XP and streaks<br/>[gamification.py]"]
end

subgraph group_persistence["Learner data"]
  node_models["Data models<br/>[models.py]"]
  node_database[("SQLite database<br/>[agli.db]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"routes practice"| node_game
node_app -->|"renders"| node_pages
node_game -->|"reads questions"| node_bank
node_game -->|"requests recommendations"| node_engine
node_game -->|"submits answers"| node_engine
node_game -->|"evaluates awards"| node_badges
node_game -->|"queries and updates"| node_models
node_models -.->|"maps records"| node_database
node_engine -->|"updates mastery"| node_bkt
node_engine -->|"estimates ability"| node_irt
node_engine -->|"scores candidates"| node_bandit
node_engine -->|"applies rewards"| node_gamification

click node_app "https://github.com/aarguellocedeno/agli/blob/main/agli/app.py"
click node_pages "https://github.com/aarguellocedeno/agli/tree/main/agli/templates"
click node_config "https://github.com/aarguellocedeno/agli/blob/main/agli/config.py"
click node_game "https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/juego.py"
click node_bank "https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/banco.py"
click node_badges "https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/insignias.py"
click node_engine "https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/engine.py"
click node_bkt "https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/bkt_module.py"
click node_irt "https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/irt_module.py"
click node_bandit "https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/bandit_module.py"
click node_gamification "https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/gamification.py"
click node_models "https://github.com/aarguellocedeno/agli/blob/main/agli/models.py"
click node_database "https://github.com/aarguellocedeno/agli/blob/main/agli/instance/agli.db"

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_pages,node_config toneBlue
class node_game,node_bank,node_badges toneAmber
class node_engine,node_bkt,node_irt,node_bandit,node_gamification toneMint
class node_models,node_database toneRose
class node_learner toneIndigo
```

## Components

### Web experience

- [Flask app](https://github.com/aarguellocedeno/agli/blob/main/agli/app.py): `agli/app.py`
- [Practice pages](https://github.com/aarguellocedeno/agli/tree/main/agli/templates): `agli/templates`
- [App configuration](https://github.com/aarguellocedeno/agli/blob/main/agli/config.py): `agli/config.py`

### Practice services

- [Practice coordinator](https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/juego.py): `agli/servicios/juego.py`
- [Question bank](https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/banco.py): `agli/servicios/banco.py`
- [Badge rules](https://github.com/aarguellocedeno/agli/blob/main/agli/servicios/insignias.py): `agli/servicios/insignias.py`

### Adaptive engine

- [Adaptive engine](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/engine.py): `agli/agli_engine/engine.py`
- [Knowledge tracking](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/bkt_module.py): `agli/agli_engine/bkt_module.py`
- [IRT estimation](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/irt_module.py): `agli/agli_engine/irt_module.py`
- [LinUCB selection](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/bandit_module.py): `agli/agli_engine/bandit_module.py`
- [XP and streaks](https://github.com/aarguellocedeno/agli/blob/main/agli/agli_engine/gamification.py): `agli/agli_engine/gamification.py`

### Learner data

- [Data models](https://github.com/aarguellocedeno/agli/blob/main/agli/models.py): `agli/models.py`
- [SQLite database](https://github.com/aarguellocedeno/agli/blob/main/agli/instance/agli.db): `agli/instance/agli.db`

### Other components

- **Learner**

## Connections

- Learner → Flask app: uses
- Flask app → App configuration: loads settings (evidence: `agli/app.py`)
- Flask app → Practice coordinator: routes practice (evidence: `agli/app.py`)
- Flask app → Practice pages: renders (evidence: `agli/app.py`)
- Practice coordinator → Question bank: reads questions (evidence: `agli/servicios/juego.py`)
- Practice coordinator → Adaptive engine: requests recommendations (evidence: `agli/servicios/juego.py`)
- Practice coordinator → Adaptive engine: submits answers (evidence: `agli/servicios/juego.py`)
- Practice coordinator → Badge rules: evaluates awards (evidence: `agli/servicios/juego.py`)
- Practice coordinator → Data models: queries and updates (evidence: `agli/servicios/juego.py`)
- Data models → SQLite database: maps records
- Adaptive engine → Knowledge tracking: updates mastery (evidence: `agli/agli_engine/engine.py`)
- Adaptive engine → IRT estimation: estimates ability (evidence: `agli/agli_engine/engine.py`)
- Adaptive engine → LinUCB selection: scores candidates (evidence: `agli/agli_engine/engine.py`)
- Adaptive engine → XP and streaks: applies rewards (evidence: `agli/agli_engine/engine.py`)