proj/.grokkit/analysis.md

# Project Analysis: proj

## Tech Stack & Layout
- Language (strict C90 / ANSI C89), no build system (simple compilation with standards-compliant compilers like gcc -ansi or Turbo C++), supported platforms (modern Unix, macOS, Windows via MinGW or Cygwin, DOS 6.22 with Turbo C++)
- Why these choices were made (portability across decades-old and modern systems without relying on C99+ features; minimal dependencies to ensure it "does one thing well" like a Unix tool, avoiding external libs for broad compatibility and simplicity)
- High-level directory structure and purpose of each major directory/file
  - `.` (root): Contains Git configuration for version control, with remotes pointing to a Gitea repository for source hosting
  - `src/`: Core source code directory; contains `main.c` as the single entry point for the entire program, handling all logic from CLI parsing to output

## Module & Function Relationships
- How modules and functions relate to each other: With only a single source file (`src/main.c`), all functions are defined inline or as static helpers within `main.c`; the program flows from `main()` entry point to utility functions for argument parsing, data processing, and output, promoting a monolithic yet portable structure
- Shared utilities and internal code organization (`src/`, `include/`, common helpers): No separate `include/` directory (headers are minimal or inlined); common helpers in `main.c` include string manipulation, CSV parsing routines, and terminal detection functions that are called sequentially from `main()`; utilities are not modularized into separate files to minimize compilation complexity on legacy systems like DOS

## Function & Method Reference
**Grouped by responsibility in `src/main.c` (CLI Parsing and Main Loop):**
- `main(int argc, char *argv[])`: Serves as the program entry point, parsing command-line arguments to determine actions like adding or listing notes; it orchestrates data flow by calling helpers for CSV I/O and output formatting
  - How it works (key logic, string/CSV handling, memory management, terminal width detection, etc.): Uses manual string comparison (e.g., `strcmp`) for args, allocates memory with `malloc` for note storage, detects terminal width via `getenv("COLUMNS")` or fallback to 80 chars for portability, and handles CSV by tokenizing strings with custom loops avoiding `strtok` for C90 purity
  - Why it exists (design rationale, portability concern, Unix philosophy, or immutability requirement): Embodies Unix "do one thing well" by being a simple CLI tool; ensures portability by avoiding non-standard APIs, and enforces immutability by appending to CSV without deletions

**CSV Handling Functions:**
- `parse_csv_line(char *line, char **fields, int max_fields)`: Tokenizes a CSV line into fields without external libs
  - How it works (key logic, string/CSV handling, memory management, terminal width detection, etc.): Iterates through the string with pointers, handling quotes and commas manually; allocates arrays with `malloc` and frees them explicitly to manage memory in C90 style
  - Why it exists (design rationale, portability concern, Unix philosophy, or immutability requirement): Provides self-contained CSV parsing for note storage, avoiding dependencies for portability across platforms like DOS where libs may not exist; supports immutable archiving by reading without modifying source files

- `write_csv_note(FILE *fp, const char *note)`: Appends a new note to a CSV file
  - How it works (key logic, string/CSV handling, memory management, terminal width detection, etc.): Escapes special characters in the note string, formats as CSV row, and writes via `fprintf`; no memory allocation needed beyond stack usage for simplicity
  - Why it exists (design rationale, portability concern, Unix philosophy, or immutability requirement): Enables immutable logging where notes are appended only, never deleted or edited, aligning with archival safety; uses standard `stdio.h` for cross-platform file I/O

**Output and Utility Functions:**
- `print_notes(char **notes, int count)`: Displays notes adapted to terminal width
  - How it works (key logic, string/CSV handling, memory management, terminal width detection, etc.): Queries terminal width with portable methods (e.g., `ioctl` fallback or env var), wraps lines manually using string length checks, and outputs via `printf`
  - Why it exists (design rationale, portability concern, Unix philosophy, or immutability requirement): Ensures readable CLI output without curses dependency, promoting shell composability; handles portability by providing DOS-safe fallbacks like fixed-width output

- `archive_note(const char *note_id)`: Moves a note to an archive CSV without deletion
  - How it works (key logic, string/CSV handling, memory management, terminal width detection, etc.): Reads source CSV, copies non-matching rows to a temp file, appends the matched note to archive, then renames files; manages buffers with `malloc`/`free`
  - Why it exists (design rationale, portability concern, Unix philosophy, or immutability requirement): Implements immutable archiving (notes are never truly deleted, just relocated) for data integrity; avoids modern file APIs for C90 compliance

## Object & Data Flow
- Main data structures (especially how notes are stored and manipulated in CSV format): Notes stored as simple CSV files (e.g., rows with ID, timestamp, text); in-memory representation uses arrays of `char*` allocated via `malloc` for lists of notes, with manual indexing instead of structs for C90 simplicity
- Flow of data from command-line arguments → processing → output or archive: Args parsed in `main()` → CSV file read/parsed into memory arrays → processing (e.g., append or archive via helper functions) → output formatted for terminal or written back to CSV/archive file; immutability ensures original data is appended to, not overwritten
- Error handling and safety patterns used under strict C90 constraints: Checks return values of all functions (e.g., `fopen` != NULL), uses `errno` for I/O errors, manual cleanup with `free` in error paths; no exceptions, so flow control via early returns and status codes for portability

## Learning Path & Gotchas
- Recommended order to read and understand the codebase: Start with `main()` to grasp CLI flow, then study CSV parsing helpers for data handling, followed by output functions for portability tricks, and end with archiving logic to understand immutability
- Common pitfalls for newcomers to strict C90 / legacy-compatible C: Forgetting manual `free` after `malloc` leading to leaks; assuming C99 features like variable-length arrays (use fixed sizes instead); overlooking pointer arithmetic in string handling
- Portability gotchas (DOS vs Unix differences, Turbo C++ quirks, `getenv`, `system()`, file I/O): DOS limits file paths and lacks `getenv` for some vars (use fallbacks); Turbo C++ may require `#define` for ANSI compliance; `system()` behaves differently (e.g., no shell on DOS); file I/O must handle text/binary modes with `fopen "rb"/"wb"` for cross-platform consistency
- Why certain design decisions were made (immutability, no external libs, single-purpose tools): Immutability prevents data loss in archival tools; no libs ensure portability to minimal environments like DOS; single-purpose design follows Unix philosophy for composable CLI utilities, keeping the codebase lean and educational