Todo CLI in Rust 0. Series roadmap and repository map

Hey folks.

Read this chapter in Spanish: ES

This post is the gateway to the series. The idea is simple: open the repository while reading, and follow every design decision in real code instead of staying in theory land.

Project repository:

• github.com/rafafrdz/todo-cli-rs

Original challenge inspiration:

• CodeCrafters Rust Projects (Project #1)

How to read this series (without getting lost)

#

Recommended order:

1. architecture and boundaries,
2. domain and errors,
3. CLI and output contract,
4. persistence and testing,
5. evolution to a TUI with ratatui.

That order is intentional. It mirrors how the project was built: first structural decisions, then implementation by layer.

Series chapters

#

1) Architecture

#

• Post: Todo CLI in Rust 1. Hexagonal architecture in a small project
• Recommended link: docs/architecture.md
• Companion: docs/step-1-mvp.md

This chapter explains why we chose hexagonal + screaming architecture for a small project, and what pain it avoids when you start iterating.

2) Domain and errors

#

• Post: Todo CLI in Rust 2. Immutable domain and typed errors by layer
• Links:
  • src/tasks/domain/task.rs
  • src/tasks/domain/errors.rs
  • src/tasks/application/errors.rs

This is the core: invariants, state transitions, and error propagation with context.

3) CLI layer

#

• Post: Todo CLI in Rust 3. Building the CLI with clap
• Links:
  • src/tasks/adapters/cli/cli_command.rs
  • src/tasks/adapters/cli/printer.rs
  • src/main.rs

This connects terminal UX with a technical contract: strict parsing, typed Uuid, and table/json output.

4) Persistence and testing

#

• Post: Todo CLI in Rust 4. JSON persistence, testing, and scale-ready decisions
• Links:
  • src/tasks/ports/outputs/task_repository.rs
  • src/tasks/adapters/persistence/in_memory_task_repository.rs
  • src/tasks/adapters/persistence/json_file_task_repository.rs

This chapter closes the loop: repository contract, interchangeable adapters, operation semantics, and behavior-focused tests.

5) Future: from CLI to TUI

#

• Post: Todo CLI in Rust 5. Next step: moving from CLI to a TUI with ratatui
• Links:
  • ratatui.rs
  • src/tasks/application/use_cases
  • src/tasks/domain/task.rs

This chapter proposes the natural evolution: add a new UI adapter (TUI) while reusing the current domain and use cases.

What you get from the full series

#

• how to design a Rust CLI without turning main.rs into a monolith,
• how to isolate domain, application, and infrastructure,
• how to model errors so they help both user and developer,
• how to prepare the project for iteration without painful rewrites.

If your goal is to build terminal tools that survive real change, this series is much more useful than a 15-minute todo tutorial.