Designing Data-Intensive Applications Interactive Edition

An interactive learning platform for Chapter 1 of Designing Data-Intensive Applications (2nd Edition).

The project turns long-form technical book content into a structured learning experience with guided modules, progressive question gating, persisted learner progress, and AI-assisted feedback. It is built with Flask, Jinja, vanilla JavaScript, and SQLite.

This project is built around Designing Data-Intensive Applications, 2nd Edition by Martin Kleppmann and Chris Riccomini, published by O'Reilly Media. The source book PDF is not included in this repository for copyright reasons. Official book page: https://www.oreilly.com/library/view/designing-data-intensive-applications/9781098119058/

What This Project Demonstrates

• Server-side parsing of structured markdown learning content
• A chapter/module content model that can scale beyond a single chapter
• Progressive disclosure UX with gated questions and completion-driven navigation
• SQLite-backed persistence for answers, progress, and learner stats
• AI-assisted grading with graceful fallback to reference answers
• Optional module-specific PDF excerpts derived from a local source book PDF
• A responsive frontend without a SPA framework

Core Features

• Chapter-aware content catalog with Chapter 1 currently implemented
• Interactive module pages with prompt submission and saved feedback
• Parsing of QUESTION, CORRECT_ANSWER, and GRADING_RUBRIC blocks from markdown
• Hidden answer/rubric content on initial render
• AJAX answer submission with persisted tutor feedback
• Automatic fallback when Gemini is not configured or unavailable
• Responsive image lightbox and syntax-highlighted code blocks

Project Structure

.
├── app.py
├── grader.py
├── models.py
├── config.example.yaml
├── requirements.txt
├── content/
│   ├── chapters/chapter-01/
│   ├── assets/
│   └── reference/         # local-only, gitignored book inputs
├── static/
│   ├── css/style.css
│   └── js/app.js
├── templates/
└── data/

Setup

# 1. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Copy config and add your FREE Gemini API key
cp config.example.yaml config.yaml
# Edit config.yaml
# Get your key at https://aistudio.google.com/apikey

# 4. Add optional local book-reference files
mkdir -p content/reference
# Place your local PDF at:
#   content/reference/designing-data-intensive-applications-2e.pdf
# Place your local transcript at:
#   content/reference/ddia-2e-full-transcript.md

# 5. Run the app
python app.py

# 6. Open http://localhost:5000

Stack

• Backend: Flask
• Templating: Jinja2
• Frontend: vanilla JavaScript + CSS
• Persistence: SQLite
• Content format: Markdown with structured prompt blocks
• Optional AI grading: Google Gemini

Configuration

All runtime configuration is read from config.yaml.

Key sections:

• gemini.api_key: Google AI Studio key
• gemini.model: defaults to gemini-2.0-flash
• app.secret_key: Flask secret key
• content.chapters_dir: markdown chapter directory
• content.assets_dir: shared image directory
• database.path: SQLite database location
• book.pdf_path: optional local PDF used for module book excerpts
• book.excerpt_cache_dir: generated excerpt cache directory

If config.yaml is missing, the app stops at startup with a clear error.

If the optional book PDF is not present, the rest of the app still works and the book reference viewer simply remains unavailable.

If Gemini is not configured, the app still works:

• AI grading is disabled
• students still see the reference answer
• the UI shows a banner explaining how to enable Gemini

Progress and Persistence

Learner progress is stored in SQLite:

• submitted answers
• module completion
• aggregate stats such as total answered questions and streak

The app currently assumes a single anonymous learner profile.

Repository Notes

• Only Chapter 1 is implemented right now, but the app catalog and sidebar support expansion to additional chapters later.
• config.yaml is gitignored so the only required local edit is your own configuration.
• content/reference/ is reserved for local-only reference inputs such as the source book PDF and transcript. Those files are intentionally not committed.
• The repository does not include the O'Reilly book itself. If you want the optional PDF excerpt viewer to work locally, add your own legally obtained copy to content/reference/designing-data-intensive-applications-2e.pdf.