CurseTechnique/learning/walkthrough.md

CurseTechnique Codebase Walkthrough

This document is a practical map of the app, aimed at learning-oriented Rust reading.

1. High-level architecture

The app uses a lightweight 4-layer layout:

1. src/main.rs - startup and route wiring
2. src/handlers.rs - HTTP handlers and input validation
3. src/db.rs - SQLite queries and data structs
4. src/views.rs - HTML rendering (server-side string rendering)

The goal is to keep each file focused and easy to read without adding extra frameworks.

2. Request flow (end-to-end)

Example: open GET /day/2026-02-07

1. Route is defined in src/main.rs and points to handlers::show_day_entries.
2. show_day_entries in src/handlers.rs validates the date path param.
3. It calls db::fetch_day_entries in src/db.rs to load rows from SQLite.
4. It passes those rows to views::render_day_page in src/views.rs.
5. The rendered HTML is returned to the browser.

Example: submit add-entry form POST /day/{date}/add

1. Route points to handlers::create_entry.
2. Handler validates date and form fields (name, calories).
3. Handler calls db::insert_entry.
4. Handler redirects back to /day/{date}.

3. File-by-file reading guide

src/main.rs

Read this file first. It is intentionally small.

• Creates data directory and opens SQLite DB.
• Calls DB init/seed helpers.
• Builds Axum router.
• Starts Tokio TCP listener.

If you ever wonder "where is this endpoint connected?", this file is the source of truth.

src/handlers.rs

This is the HTTP boundary.

Core concepts here:

• AppState holds shared DB connection behind Arc<Mutex<Connection>>.
• Each handler receives typed route/form data.
• Handlers do three steps:
  1. Validate input
  2. Call DB function
  3. Return HTML or redirect

Useful helper functions:

• validate_date ensures YYYY-MM-DD format.
• parse_entry_form_fields validates name + calories.
• month_bounds computes first/next month boundaries.

src/db.rs

This file contains all SQL.

Data structs:

• FoodEntry represents one row.
• DaySummary represents aggregated values for calendar cards.

Functions are split by intent:

• Setup: init_db, seed_db_if_empty
• Reads: fetch_month_summaries, fetch_day_entries
• Writes: insert_entry, update_entry, delete_entry

If behavior looks wrong (totals, filtering, ordering), start debugging here.

src/views.rs

This file builds HTML strings for SSR.

• render_calendar_page renders /.
• render_day_page renders /day/{date}.
• Small helpers reduce clutter:
  • render_day_card
  • render_entry_rows
  • entry_count_label
  • escape_html

Important: escape_html is used when rendering user-provided food names.

4. Key Rust patterns used

• Result<T, E> for explicit error handling.
• ? operator to propagate errors.
• Arc<Mutex<_>> for shared mutable state across async handlers.
• Simple structs over tuple-heavy values for readability (DaySummary).
• Module organization (mod db; mod handlers; mod views;) to keep files focused.

5. How to add a feature safely

Use this checklist:

1. Add/adjust SQL function in db.rs.
2. Add or update handler logic in handlers.rs.
3. Update route wiring in main.rs if endpoint path changes.
4. Update HTML output/forms in views.rs.
5. Run:
   • cargo fmt
   • cargo check

6. Suggested beginner exercises

1. Add a "notes" text column to food entries.
2. Show count of entries in the day header.
3. Add confirmation step on delete (simple query param or separate page).
4. Add a helper in handlers to prevent editing future dates.

These exercises touch all 4 layers and are great practice for understanding the whole flow.