vibed/nbd/docs/ARCHITECTURE.md

nbd — Architecture

Overview

nbd is a single-binary CLI tool with no background service. All state lives in .nbd/tickets/ inside the project directory tree. The binary is structured as four modules, each with a single responsibility:

src/
├── main.rs      CLI definition and command dispatch
├── ticket.rs    Data model, ID generation, priority validation
├── store.rs     File I/O, directory traversal, CRUD
└── display.rs   Human-readable and JSON output formatting

Module Responsibilities

main.rs — CLI entry point

Owns the clap struct definitions (Cli, Commands) and the top-level main function. Delegates all business logic to command handlers (cmd_create, cmd_read, cmd_list, cmd_update). The handlers are thin: they call helpers from store, ticket, and display, then return.

Parsing helpers (parse_status, parse_ticket_type, parse_deps) live here because they translate raw CLI strings into typed values used only by the command handlers.

ticket.rs — Data model

Defines the canonical in-memory representation of a ticket:

• Ticket struct — all fields
• Status enum — Todo | InProgress | Done
• TicketType enum — Project | Feature | Task | Bug

Provides two free functions:

• generate_id() -> String — uses RandomState (seeded with OS entropy) to produce a 6-character lowercase hex string. No external randomness crate needed.
• validate_priority(u8) -> Result<(), String> — enforces the 0–10 range.

The enums derive serde's Serialize/Deserialize with #[serde(rename_all)] so the JSON representation uses lowercase strings ("in_progress", "bug", …).

store.rs — File I/O

All filesystem operations are in this module. Uses async-std for async I/O throughout.

Directory discovery:

find_nbd_root()
  └─ find_nbd_root_from(cwd)
       Walk parent dirs until .nbd/ is found

find_nbd_root_from accepts an explicit starting path to make it testable without changing the process's working directory.

CRUD functions:

Function	Operation
ensure_tickets_dir(root)	Create .nbd/tickets/ if missing
write_ticket(root, ticket)	Serialise → pretty JSON → write file
read_ticket(root, id)	Read file → deserialise; friendly error if not found
list_tickets(root)	Read all *.json → sort by priority desc

Error type: store::Result<T> is aliased to Result<T, Box<dyn Error + Send + Sync>>, allowing ? to propagate both io::Error and serde_json::Error without explicit wrapping.

display.rs — Output formatting

Two output modes:

• Tabular — human-readable key–value block (single ticket) or column-aligned table (list). Column widths are compile-time constants.
• JSON — delegates to serde_json::to_string_pretty.

Each public surface is split into a format_* function (returns String, testable) and a print_* function (writes to stdout via println!).

Data Flow

CLI args (clap)
      │
      ▼
  dispatch()          [main.rs]
      │
      ├── parse_* helpers  ──►  typed values
      │
      ├── store::find_nbd_root()     ──►  PathBuf
      ├── store::read_ticket()       ──►  Ticket
      ├── store::list_tickets()      ──►  Vec<Ticket>
      ├── store::write_ticket()      ──►  ()
      │
      └── display::print_ticket()   ──►  stdout
          display::print_list()     ──►  stdout

Storage Layout

<project-root>/
└── .nbd/
    └── tickets/
        ├── a3f9c2.json
        ├── b7d41e.json
        └── ...

Each file is a pretty-printed JSON object with the fields of Ticket. File name equals the ticket's id field with a .json extension.

Testing Strategy

• Unit tests (src/tests.rs): exercise ticket.rs, store.rs, and display.rs in isolation using tempfile::TempDir for any file I/O.
• Integration tests (tests/integration.rs): drive full command flows (create → read → list → update) through cmd_* functions against a temporary directory. Include a directory-traversal test that invokes commands from a nested subdirectory.