From 1d16056f4f122f9312b2eb2c32141eaf019b83aa Mon Sep 17 00:00:00 2001 From: Don Harper Date: Sat, 13 Jun 2026 23:56:07 -0500 Subject: [PATCH] Add PROJECT_DOCUMENTATION.md --- PROJECT_DOCUMENTATION.md | 165 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 PROJECT_DOCUMENTATION.md diff --git a/PROJECT_DOCUMENTATION.md b/PROJECT_DOCUMENTATION.md new file mode 100644 index 0000000..71ec940 --- /dev/null +++ b/PROJECT_DOCUMENTATION.md @@ -0,0 +1,165 @@ +# Pen Tracker Project Documentation + +## Overview + +`pen-tracker` is a small Python package for tracking fountain pens and inks using CSV storage. It provides a single command-line interface (`pen-tracker`) for interactive data management, plus direct CLI commands for adding, listing, exporting, and maintaining the collection. + +This repository is structured as a standard Python package with source under `src/pen_tracker`, package metadata in `pyproject.toml`, and a small test suite under `tests`. + +## Key goals + +- Maintain a pen collection with fields such as make, model, nib, ink, purchase date, and notes. +- Maintain an ink collection separately with vendor, name, color, purchase date, size, and notes. +- Store data in CSV files for compatibility and simplicity. +- Use a single CLI entry point for developer and automation workflows. + +## Repository layout + +- `pyproject.toml` — packaging metadata, dependencies, and entry points. +- `README.md` — user-facing usage documentation. +- `PROJECT_DOCUMENTATION.md` — developer/AI reference documentation. +- `src/pen_tracker/engine.py` — domain logic, data models, CSV persistence, and storage defaults. +- `src/pen_tracker/cli.py` — command-line interface, interactive menus, and command parsing. +- `tests/test_engine.py` — basic test coverage for core engine behavior. + +## Core components + +### `src/pen_tracker/engine.py` + +Primary responsibilities: + +- Define `Pen` and `Ink` dataclasses. +- Provide `PenTracker` and `InkTracker` classes that: + - Decide storage path from environment or default XDG data directories. + - Load CSV files into Python objects. + - Normalize data on load. + - Persist sorted CSV output. + +Important details: + +- Default pen storage path: `~/.local/share/pen-tracker/pens.csv` +- Default ink storage path: `~/.local/share/pen-tracker/inks.csv` +- Environment overrides: + - `PEN_TRACKER_CSV` for pen storage. + - `INK_TRACKER_CSV` for ink storage. +- `PenTracker.load_data()` maps CSV headers like `Date-Purchased` and `Current-Ink` to dataclass fields like `Date_Purchased` and `Current_Ink`. +- CSV headers are written using the original hyphenated naming convention. + +### `src/pen_tracker/cli.py` + +Primary responsibilities: + +- Parse command-line arguments with `argparse`. +- Provide commands for: + - `add` — add a new pen from CLI inputs. + - `list` — display all pens. + - `export` — export pens to JSON. + - `add-ink` — add a new ink. + - `list-inks` — list saved inks. +- Provide an interactive text menu when no command is supplied. +- Display one-based IDs for pens and inks. +- Validate user input and dates. + +## Usage patterns + +### Installation + +```bash +pip install . +``` + +### Run interactive CLI + +```bash +pen-tracker +``` + +### Add a pen via CLI + +```bash +pen-tracker add --make "Pilot" --model "Metropolitan" --nib "F" +``` + +### List saved pens + +```bash +pen-tracker list +``` + +### Export pens to JSON + +```bash +pen-tracker export --output my_pens.json +``` + +### Add an ink via CLI + +```bash +pen-tracker add-ink --vendor "Diamine" --name "Majestic Blue" --color "Blue" +``` + +### List inks + +```bash +pen-tracker list-inks +``` + +## Data model + +### Pen fields + +- `Make` +- `Model` +- `Date_Purchased` / `Date-Purchased` +- `Vendor` +- `Nib` +- `Nib_Material` / `Nib-Material` +- `Body` +- `Cap` +- `Post` +- `Current_Ink` / `Current-Ink` +- `Inked_date` / `Inked-date` +- `Notes` + +### Ink fields + +- `Vendor` +- `Name` +- `Color` +- `Purchased` +- `Size` +- `Notes` + +## Packaging and scripts + +The package is configured with `pyproject.toml` and uses `setuptools.build_meta` as the build backend. There are no runtime dependencies. + +Entry point: + +- `pen-tracker = pen_tracker.cli:main` + +## Developer notes + +- The CLI is the only supported interface. The repository no longer includes any TUI or graphical code. +- When modifying storage columns, update both `engine.py` and `cli.py` to maintain header mapping and CSV serialization. +- One-based IDs are used consistently for user-facing selection and display. +- CSV persistence always sorts data before saving. + +## Testing + +- `tests/test_engine.py` contains test coverage for the core engine layer. +- Add tests for new fields, storage behavior, and CLI data validation if extending features. + +## Notes for AI agents + +- Focus on `src/pen_tracker/engine.py` for the data model and persistence logic. +- Focus on `src/pen_tracker/cli.py` for user-facing behavior, commands, and interactive menu flow. +- The default storage paths are derived from XDG conventions and environment variables. +- There is no GUI, web service, or database; all data is stored in CSV files. +- The project version is `0.5.0` and the package name is `pen-tracker`. + +## Extension suggestions + +- Add unit tests for the CLI parser and interactive menu flows. +- Add a dedicated `docs/` folder if more formal design docs or API references are needed. +- Add JSON schema validation or stronger date handling if data robustness is required.