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.