Project 6: Habit Tracker Service

The scenario

A small product team wants a habit tracker. Users create habits ("Drink water", "Gym on Mon/Wed/Fri", "Weekly review"), check in when they do them, and look at their streaks (how many periods in a row they kept the habit) and completion rate (what fraction of due periods they kept). Today it is a command-line tool backed by a SQLite file. Next quarter the team wants a web API (Module 45's FastAPI) and maybe PostgreSQL. Your job is to build version 1 so that those changes touch only the edges of the code.

That requirement drives the architecture. The rules about dates and streaks are the valuable, subtle part, so they live in a domain module with no I/O at all. Storage is hidden behind a port (an interface), so a SQLite adapter and an in-memory adapter are interchangeable. The service layer expresses each use case once. The CLI is a thin composition root: the one place that picks concrete classes and wires them together.

Learning goals

Feature specification

Frequencies and periods

Every habit has a frequency, and every frequency splits time into periods. A period is identified by its key, the date it starts on.

Rules

• Habit ids are slugs of the name: "Drink Water!" becomes drink-water. Names are 1–80 characters after stripping; duplicate ids are rejected.
• Check-in is idempotent per period. Checking in a weekly habit on Monday and again on Thursday stores one completion; the second call returns False.
• Check-ins in the future, before the habit was created, on a day that is not due, or on an archived habit raise ValidationError. Unknown ids raise NotFoundError.
• Undo removes the check-in for the period that contains the given day (default today).
• Current streak: consecutive satisfied periods ending at the current one. Today's period is still in progress, so leaving it unchecked does not break the streak; a missed finished period does.
• Longest streak: the best run of consecutive satisfied periods from creation until today.
• Completion rate over start..end: satisfied due periods divided by due periods, ignoring periods before creation (0.0 if there are none). The default window is the 30 days ending today.
• Export: JSON (every habit with its list of check-in dates and streaks) and CSV (one row per habit with the check-in count).

The CLI

pixi run python -m habits --db demo.db add "Gym" --frequency mon,wed,fri
created gym (mon,wed,fri)
pixi run python -m habits --db demo.db checkin gym
checked in gym
pixi run python -m habits --db demo.db checkin gym --date 2026-01-05   # backfill
pixi run python -m habits --db demo.db list --all
pixi run python -m habits --db demo.db stats gym --from 2026-01-01 --to 2026-01-31
habit: gym
current_streak: 4
longest_streak: 6
completed: 10/13
completion_rate: 76.9%
pixi run python -m habits --db demo.db export --format json > backup.json
pixi run python -m habits -v --today 2026-02-01 undo gym       # -v shows info logs on stderr

Global options: --db PATH (default $HABITS_DB, else habits.db), --today YYYY-MM-DD (pretend it is that date; great for demos and tests), and -v. Exit code 0 means success, 1 means a HabitError (message on stderr as error: ...), and 2 is argparse's usage error.

Architecture

Dependencies point inward. The domain imports nothing from the project. Ports import only the domain. The service imports the domain and the ports, never an adapter. Only the CLI knows that SQLite exists.

flowchart LR
  subgraph Outside["Driving side"]
    CLI["cli.py
argparse + structlog
(composition root)"]
  end
  subgraph Core["Application core"]
    SVC["service.py
HabitService use cases"]
    DOM["domain.py
Habit, Frequency, Completion
streaks, rates"]
    PORTS["ports.py
HabitRepository, Clock
(Protocols)"]
  end
  subgraph Driven["Driven side (adapters)"]
    MEM["memory.py
InMemoryRepository"]
    SQL["sqlite_repo.py
SqliteRepository
migrations + transactions"]
    CLK["SystemClock / FixedClock"]
  end
  CLI --> SVC
  CLI -. builds .-> SQL
  CLI -. builds .-> CLK
  SVC --> PORTS
  SVC --> DOM
  PORTS --> DOM
  MEM -. satisfies .-> PORTS
  SQL -. satisfies .-> PORTS
  CLK -. satisfies .-> PORTS
    

projects/p06_habit_tracker/
  starter/habits/          # what you copy with `pixi run start p06`
    domain.py  ports.py  memory.py  sqlite_repo.py  service.py  cli.py  logging_config.py  __main__.py
  tests/
    test_habits_domain.py  test_habits_repository.py  test_habits_service.py  test_habits_cli.py

The SQLite schema (given in MIGRATIONS; you write the code that applies it):

erDiagram
  HABITS ||--o{ COMPLETIONS : has
  HABITS {
    TEXT id PK
    TEXT name
    TEXT frequency
    TEXT created_on
    INTEGER archived
  }
  COMPLETIONS {
    TEXT habit_id FK
    TEXT day
  }
  SCHEMA_VERSION {
    INTEGER version
  }
    

Getting started with Pixi

pixi run projects            # list projects and whether you've started them
pixi run start p06           # copy the starter into work/p06_habit_tracker/
pixi run grade p06           # run all 97 tests against your work/ copy
pixi run practicum grade p06 -k domain       # only Milestone 1
pixi run practicum grade p06 -k repository   # only Milestone 2
pixi run ruff check work/p06_habit_tracker
pixi run mypy --strict work/p06_habit_tracker

The starter has every public class and function with its full signature, type hints, and docstring. Bodies raise NotImplementedError and carry TODO comments. The Protocols in ports.py, the structlog setup, the migration SQL, and the argparse parser are given so you can focus on behavior. At the top of some modules a comment lists the imports the reference solution uses.

Milestones

Hints

key = last_due_period(habit, today)
if key not in done and key == freq.period_start(today):
    key = freq.previous_period(key)       # today is still in progress
streak = 0
while key >= first and key in done:
    streak += 1
    key = freq.previous_period(key)

for version in range(current, LATEST_VERSION):
    with conn:
        conn.execute("BEGIN")
        for statement in MIGRATIONS[version]:
            conn.execute(statement)
        conn.execute("UPDATE schema_version SET version = ?", (version + 1,))

@pytest.fixture(params=["memory", "sqlite"])
def repo(request, tmp_path):
    if request.param == "memory":
        yield InMemoryRepository()
    else:
        with SqliteRepository(tmp_path / "habits.db") as sqlite_repo:
            yield sqlite_repo

Rubric

Passing pixi run grade p06 covers the first four rows. The last row is yours to verify with ruff and mypy, exactly as a CI pipeline (M42) would.

Stretch goals

• A third migration. Add a notes column and a rename use case. Prove an old database upgrades by writing a test that builds a version-2 file first.
• "N times per week". Add a frequency such as 3x/week. What does a streak mean now? Write the tests before the code.
• A third adapter. Write JsonFileRepository and add "json" to the contract fixture's params. If the contract tests pass, the service works with it unchanged.
• A web front end. Wrap HabitService in a FastAPI app (Module 45) with Depends providing the service. The domain, ports, and adapters should not change at all.
• SQLAlchemy. Implement the repository with SQLAlchemy 2.0 Core and compare it to the raw sqlite3 version.

Reflection quiz