📝 A standalone notes + to-do app in Python — and the step-by-step course that builds it.

Read a chapter · run the code · git switch --detach chNN to see exactly what that chapter built.

⭐ If a Forkable* repo saves you an afternoon, a star helps someone else find it.

---

👋 At a glance

Info	Details
🎯 What	A notes app with checklists, instant search and a purple light/dark theme — running in your browser, served from your own computer
📚 How you learn	5 sections · 12 chapters, each ending in a Git tag (ch00 … ch11) you can check out
🧰 Stack	Python Flask Jinja2 Waitress SQLite FTS5 HTML CSS JS pytest Playwright GitHub Actions PyInstaller
💻 Runs on	🍎 macOS · 🪟 Windows · 🐧 Linux — Python 3.10 or newer
🔒 Privacy	Listens on 127.0.0.1 only. No account, no cloud, no analytics — and a test proves nothing leaves your machine
🗺️ Part of	The Forkable* index — clone it, run it, keep it or throw it away

⚡ Quick start

🍎 macOS · Terminal (zsh)	🪟 Windows · PowerShell
git clone https://github.com/suryakulshreshtha/Forkable-ToDoNotes.git cd Forkable-ToDoNotes python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python -m todonotes # opens http://127.0.0.1:8765/	git clone https://github.com/suryakulshreshtha/Forkable-ToDoNotes.git cd Forkable-ToDoNotes py -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt python -m todonotes # opens http://127.0.0.1:8765/

Stop it with Ctrl+C. Your notes are kept in one SQLite file in your user data folder (details in Chapter 03).

📦 Prefer a double-click app?

Every version tag builds ready-to-run apps for macOS (Apple Silicon and Intel), Windows and Linux on the Releases page. They are not code-signed yet — see Chapter 10 for the one-time "Open Anyway" step.

🖼️ Screenshots

🌙 Dark	☀️ Light

_{Captured automatically by Playwright — scripts/capture_screenshots.py.}

🗺️ How it fits together

%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f3d7f7", "primaryTextColor": "#46104c", "primaryBorderColor": "#5316a6", "lineColor": "#672891", "secondaryColor": "#e7c1ee", "tertiaryColor": "#f8f2fa", "fontFamily": "Helvetica, Arial, sans-serif"}}}%%
flowchart TB
    subgraph APP["📝 The app — runs on 127.0.0.1 only"]
        direction LR
        B["🌐 Browser<br/>HTML · CSS · JS<br/><i>ch05–06</i>"] -- "HTTP request" --> W["🧭 web.py<br/>Flask routes<br/><i>ch05</i>"]
        W -- "render" --> T["🎨 Templates<br/>Jinja2 + theme.css<br/><i>ch05–06</i>"]
        T -- "HTML page" --> B
        W -- "calls" --> S["🧠 service.py<br/>rules · validation<br/><i>ch04</i>"]
        S -- "calls" --> R["🗄️ storage.py<br/>SQL only<br/><i>ch03</i>"]
        R -- "sqlite3" --> D[("💾 notes.db<br/>SQLite + FTS5<br/><i>ch03 · ch07</i>")]
    end
    subgraph AUTO["🎭 Automation — proves it works"]
        direction LR
        PW["Playwright<br/><i>ch08–09</i>"] -- "drives" --> B
        PY["pytest<br/><i>ch01–09</i>"] -- "tests" --> S
    end
    subgraph SHIP["🚀 Ship — from commit to download"]
        direction LR
        G["git<br/>chapter tags"] --> GH["GitHub"] --> A["Actions<br/>CI gate · <i>ch10</i>"] --> PI["PyInstaller"] --> REL["📦 Releases<br/>macOS · Windows · Linux"]
    end
    APP ~~~ SHIP
    classDef app fill:#f3d7f7,stroke:#5316a6,color:#46104c
    classDef auto fill:#e7c1ee,stroke:#672891,color:#46104c
    classDef ship fill:#f1e4f4,stroke:#46104c,color:#46104c
    class B,W,T,S,R,D app
    class PW,PY auto
    class G,GH,A,PI,REL ship

Loading

_{🖼️ Offline copy: tech-map.svg · source: tech-map.mmd}

📚 Learning path — sections and chapters

🧭 Section 1 · Orientation

Chapter	What you'll build	Stack	Tag
00 · How to read this repo	The map, the conventions, following along with tags	Git Markdown	ch00
01 · Setup: Python, Git, venv	A working toolchain on 🍎 and 🪟, an installable package, the first test	Python pip venv pytest ruff	ch01
02 · Architecture & data flow	Layers, Mermaid diagrams, documentation that is tested	Mermaid pytest	ch02

🗄️ Section 2 · Data & logic

Chapter	What you'll build	Stack	Tag
03 · SQLite storage	Schema, migrations, parameters, per-OS data folder	SQLite sqlite3	ch03
04 · Service layer & unit tests	Business rules, fixtures, parametrize, markers	Python pytest	ch04

🎨 Section 3 · Web UI

Chapter	What you'll build	Stack	Tag
05 · Flask routes & templates	Pages, forms, JSON API, local-only safety checks	Flask Jinja2 Waitress	ch05
06 · Design system: CSS & JS	Purple palette tokens, light/dark, contrast tests, autosave	CSS JavaScript WCAG	ch06
07 · Full-text search (FTS5)	Prefix search, ranking, safe <mark> highlights	SQLite FTS5 MarkupSafe	ch07

🎭 Section 4 · Automation

Chapter	What you'll build	Stack	Tag
08 · Playwright foundations	Live server fixture, page objects, first browser tests	Playwright pytest	ch08
09 · Playwright showcase	API+UI hybrids, offline proof, emulation, screenshots	Playwright	ch09

🚀 Section 5 · Ship & share

Chapter	What you'll build	Stack	Tag
10 · CI & releases	A CI gate on 3 OSes, one-file apps on GitHub Releases	GitHub Actions PyInstaller	ch10
11 · Fork, extend & audit	Make it yours, audit the supply chain, pick a next feature	Git Dependabot	ch11

📌 Suggested reading order

Section 1  🧭  00 → 01 → 02     read the map, set up, see the whole design
Section 2  🗄️  03 → 04          data first, rules second (no web yet!)
Section 3  🎨  05 → 06 → 07     pages, then looks, then search
Section 4  🎭  08 → 09          prove it works in a real browser
Section 5  🚀  10 → 11          ship it, then make it yours

Full index with time estimates: 📚 docs/README.md.

🗂️ Repository map

Files arrive chapter by chapter — the right-hand column says when.

Forkable-ToDoNotes/
├── src/todonotes/          the app
│   ├── __main__.py         launcher: picks a port, starts Waitress, opens the browser   (ch01, ch05)
│   ├── config.py           where notes.db lives on each OS                             (ch03)
│   ├── models.py           Note · ChecklistItem · SearchHit                             (ch03, ch07)
│   ├── storage.py          all SQL: migrations, CRUD, FTS5 search                       (ch03, ch07)
│   ├── service.py          rules: validation, defaults, export                          (ch04)
│   ├── web.py              Flask routes, JSON API, safety checks                        (ch05)
│   ├── templates/          Jinja HTML                                                   (ch05)
│   └── static/             theme.css · app.css · app.js                                 (ch06)
├── tests/unit/             fast tests — no browser                                      (ch01 → ch07)
├── tests/e2e/              Playwright tests + page objects                              (ch08, ch09)
├── scripts/                contrast check · screenshots · build · dependency audit
├── packaging/launch.py     PyInstaller entry point                                      (ch10)
├── .github/                CI, release workflow, issue/PR templates, Dependabot         (ch10, ch11)
└── docs/                   📚 the course: sections → chapters, diagrams, assets

🤝 Community

• 🤝 Contributing — branch, test, Conventional Commits
• 🔐 Security policy — what the app protects, how to report a problem
• 🤖 Rules for AI coding agents — may address reviews, fix CI and resolve conflicts; never merge
• 💜 Code of conduct

🔗 More Forkable* repos

Repo	What it is
ForkablePythonLearningShowcase	Test automation fundamentals, built up step by step
Forkable04EyePythonPlaywrightLearning	E2E testing workflows wired to GitHub Actions CI
ForkablePythonProjectShowcase	A full UI + API test automation framework
🗺️ The full index	Every Forkable* repo and the order to read them in

---

📄 MIT licence · 🌐 @suryakulshreshtha