# Design for aki-stats

## 1. High-Level Design

The `aki-stats` utility is designed as a standard Rust command-line application following the principle of separation of concerns. The core logic is decoupled from the application's entry point, allowing for better testability and reusability.

The architecture is composed of:
- An application entry point (`main.rs`) responsible for parsing arguments and handling process-level concerns.
- A configuration module (`conf`) to define and parse command-line inputs.
- A core processing module (`run`) that contains the primary business logic.
- A utility module (`util`) for shared components like error handling.

Data flows from the input source (stdin or file), is processed by the core logic, and the results are printed to standard output.

## 2. Module Breakdown

Based on the source code structure, the responsibilities are divided as follows:

- **`main.rs`**: 
    - The main executable entry point.
    - Parses command-line arguments using the `conf` module.
    - Invokes the core application logic in the `run` module.
    - Handles application-level exit codes and top-level error reporting.

- **`lib.rs`**:
    - The root of the library crate.
    - Declares the public modules (`run`, `conf`, `util`) to make them available to the binary.

- **`run.rs`**:
    - Contains the core functionality of the application.
    - Receives the parsed configuration from `main.rs`.
    - Manages input reading from either standard input or files.
    - Implements the text statistics calculation (lines, words, characters).
    - Formats the final statistics for display.

- **`conf/` (`mod.rs`, `parse.rs`)**:
    - Defines the command-line interface (CLI) of the application.
    - Specifies the arguments for file paths and other options.
    - Parses the arguments provided at runtime.

- **`util/` (`mod.rs`, `err.rs`)**:
    - Provides shared utilities.
    - Implements a consistent error handling strategy, likely using the `anyhow` crate.

## 3. Mapping Requirements to Design

The acceptance criteria are met by the following design components:

- **UC-1 (Process Standard Input)** & **UC-2 (Process File Input)**:
    - The `conf` module will parse the arguments to determine the input source. The `run` module will contain the logic to read from either stdin or the specified file(s).

- **UC-3 (Calculate Line Count)**, **UC-4 (Calculate Word Count)**, & **UC-5 (Calculate Character Count)**:
    - The core calculation logic resides in `run.rs`. It will process the input stream and compute these three statistics.

- **UC-6 (Display Output)**:
    - The `run.rs` module will take the calculated statistics, format them into a human-readable string (using the `num-format` crate), and print the result to standard output.

- **NFR-1 (Build Toolchain)** & **NFR-2 (Cross-Platform)**:
    - These are satisfied by using the standard `cargo` build system and relying on cross-platform Rust libraries. The design does not introduce any platform-specific components.
