Skip to content

Learning App — Developer Docs

Welcome to the developer documentation for the Word Learning Application — a Flet (Flutter + Python) app for learning vocabulary and definitions with spaced repetition.

These docs explain how this project routes screens, shares chrome, and sizes layouts. For Flet controls, Page APIs, and platform deployment, use the official Flet documentation alongside the guides below.

New here?

  1. Getting started — clone, uv sync, run the app or docs.
  2. Architecture — overview, then routing and screens for Shell/Deep and the route map (startup order).
  3. Navigation guide and Layout guide — how screens move and resize day to day.
  4. Adding a screen — step-by-step checklist once Shell/Deep and layout are clear.
  5. Concepts — routing, chrome, body registry, and the learning algorithm when you need the mechanism, not the recipe.
  6. API reference — generated signatures while you code; use it with the guides, not instead of them.

How the layers differ: Architecture maps the system, Guides are recipes, Concepts explain mechanisms, API Reference lists contracts and signatures.

For Flet control APIs and framework behavior, keep flet.dev/docs open in parallel.

To clone the repo and run the app or docs locally, see Getting started.

Documentation map

  • Architecture

    How routing, screens, layout, chrome, CSV storage, and startup wiring fit together.

    Read architecture →

  • Adding a screen

    Step-by-step checklist for shell and deep routes.

    Add a screen →

  • Guides

    Task-oriented walkthroughs: navigation, layout, state, and import/export.

    Navigation guide →

  • Concepts

    Routing registry, shell chrome, body wrappers, shared tile bodies, learning queue, and reusable UI components.

    Routing concept →

  • API reference

    Generated signatures and contracts for routing, layout, chrome, state, and CSV data.

    Browse API →

  • Flet docs

    Official reference for controls, theming, routing primitives, and deployment.

    Open flet.dev/docs →

Guides

Guide When to open it
Navigation Move between shell and deep routes from UI code.
Layout Choose LayoutKind, wrappers, and responsive sizing.
Adding a screen Register a new route and wire its control.
State and persistence Screen vs session vs preferences; theme, TTS, and learn-retry keys.
Import and export Validate CSVs, import sets, and export through the shared picker.

Concepts

Concept When to open it
Routing How RouteDef, factories, and the router cooperate.
Chrome and wrappers Shared shell chrome (config + live AppChrome / drawer) and body wrappers.
Body registry Why home and export reuse one TilesContainer instance.
Learning algorithm How AppData draws practice groups and saves answers.
UI components Tiles, learn fields, edit cards, and search controls.

Project layout

src/
  main.py                   # thin launcher: ft.run(learning_app.app.main)
  assets/                   # icons / splash / demos/ for flet build
  learning_app/
    app.py                  # app.main; wires chrome, theme, router handlers
    utils/
      greetings.py          # AppBar greeting text
    data/
      file_path_manager.py  # storage roots, csv_files, tts_cache paths
      app_data.py           # catalog CRUD, load/save, AppData session
      set_settings.py       # per-set learning and TTS overrides on files.csv
      constants.py          # CSV column enums, MAX_ROWS, import messages
      csv_processor.py      # import validation and specialized saves
      demo_sets.py          # bundled demo registry, reserved names, install
    tts/                    # pronunciation cache, gTTS provider, GC
    ui/
      route_paths.py        # canonical path constants
      route_url.py          # build and parse route URLs
      route_registry.py     # RouteDef registry, drawer, build factories
      router.py             # view stack, layout dispatch, route events
      navigation.py         # navigate_to, push_view, go_back, go_search
      inplace_search.py     # in-place SearchControl in the AppBar over tiles
      chrome_config.py      # ShellChromeConfig per shell route
      app_chrome.py         # Live AppBar / bottom bar / FAB / drawer registry
      app_drawer.py         # Shared NavigationDrawer for Shell destinations
      layout_host.py        # body wrappers: shell, deep, safe area
      layout_metrics.py     # responsive widths and breakpoint helpers
      layout_tokens.py      # shared spacing / sizing tokens
      page_functions.py     # shared dialogs and page helpers
      body_registry.py      # shared home/export TilesContainer instances
      routable_screen.py    # apply_layout protocol and view traversal
      app_session.py        # page, export FilePicker, TTS playback, navigation lock
      preferences.py        # SharedPreferences accessor
      app_theme.py          # theme mode and page bgcolor
      tts_preferences.py    # app-default TTS language, auto-speak, and speakers
      learn_preferences.py  # app-default retry flag and practice-queue sizes
      screens/              # application screens (+ _screen_template.py)
      components/           # reusable controls
tests/                      # pytest / flet test (not packaged into the app)
docs/                       # this documentation (MkDocs Material)

Clone and run steps are on Getting started. Source: github.com/BartoszKog/my-first-learning-app.