gralculator/docs/ARCHITECTURE.md

# Gralculator Architecture

## Overview
Gralculator is a terminal UI calculator inspired by the visual density and layout of galculator (GTK), but adapted for Bubble Tea + lipgloss in a keyboard-first, content-centered style consistent with the gostations project.

Core philosophy for v0.1 (MVP):
- All math is performed in decimal (float64 for simplicity).
- Display bases (DEC/HEX/BIN/OCT) are **purely for formatting** the current value in the large display area.
- A single "BASE" action (on-screen button + `Tab` key) cycles the display format: DEC → HEX → BIN → OCT → DEC.
- Non-integer values cannot be displayed in non-DEC bases. Pressing BASE on a fractional result triggers a brief "CERR" (conversion error) flash in the large display and leaves the base unchanged. This is an explicit design choice over galculator's silent truncation.
- Future iterations will add full hex digit entry (A-F), at which point letter keys will be reserved. This is why `Tab` was chosen for BASE cycling instead of a letter key.

## Package Structure
- `internal/calc` — Pure Go calculation engine. No TUI dependencies. Handles value state, pending operations, base cycling with integer checks, formatting, and arithmetic (+ - * / MOD). Fully unit-testable.
- `internal/ui` — Bubble Tea model, view, and update logic. Renders the integrated wide display row (base indicator at start of the row like `[BIN]`, followed by maximal-width right-aligned number) + keypad grid. Reuses lipgloss patterns, centering (`Place`), subtle borders, flash animations (tea.Tick + 140ms color 63 style), and content-sized card layout refined in gostations. The display spans full available width inside the card.
- `internal/version` — Version string injection (ldflags), matching gostations.
- `main.go` — Entry point, flags (-v), tea.NewProgram wiring, pre-flight checks if any.
- Root: `spec.md` (living high-level spec), `docs/` (detailed architecture and design notes), `Makefile`, `.gitignore`.

## Key Design Decisions (v0.1)
- **Internal representation**: `float64` + pending operator state (classic four-function calculator model). Simpler and sufficient for MVP. Floating-point MOD via `math.Mod`.
- **Base handling**: `CycleBase()` returns error/sentinel on non-integer to drive UI "CERR" flash. `CurrentBase()` and `FormatForDisplay()` for the view. No base-aware digit entry yet (reserved for future hex support).
- **Error on conversion**: When value has fractional part and BASE is pressed, large display shows "CERR" briefly (~600ms with flash styling), base does not change, then reverts to previous formatted value.
- **Single BASE key**: Reduces rendered keys. On-screen button labeled "BASE". Direct key is `Tab` (chosen to leave A-F free for future hex digits).
- **Display layout**: 
  - Integrated main display row inside bordered LCD panel: base indicator (e.g. [BIN]) at the left of the row, followed by the number right-aligned and spanning the maximal remaining width. Vertical padding on the container gives visual weight. (Updated from earlier separate two-row design.)
  - Small bottom row inside the same panel showing only the current base ("DEC", "HEX", "BIN", or "OCT"), highlighted when active.
- **Keypad**: Sparse 4-5 column grid for MVP (digits, operators, MOD, C, AC, single BASE button). Uses the same `makeButton` + `Width().Align(Center)` lipgloss idiom as gostations playback controls.
- **Card layout**: Entire UI is a content-sized, centered card (lipgloss.Place + rounded outer border color 63). Matches gostations Winamp-style player polish (subtle inner 238 borders, no stretching).
- **Feedback**: 140ms timed flashes (color 63 bg + white fg bold) on key actions, exactly as tuned for volume/skip/stop in gostations.
- **Hint row**: Minimal, non-wrapping, full-width (like final gostations player).
- **No persistence / config in v0.1**: Session-only current base.
- **Testing**: Engine has high-value unit tests (especially the CERR path). UI tests will focus on rendering and key-driven state transitions.
- **Future-proofing notes**:
  - Hex entry (A-F) planned for later release → letter keys kept free.
  - Scientific functions, memory, %, bitwise, word size, RPN, history, etc. explicitly deferred.
  - Potential later addition of clipboard, persistent settings (XDG), scripting subcommand.

## Build & Integration
- Matches gostations conventions: `make build`, `make install` (to `~/.local/bin/gralculator`), cross-compile support, ldflags for version.
- Binary name: `gralculator`
- Will eventually be wired into the personal REXX `~/.local/bin/apps` launcher (likely a new letter or replacement for the current "l. Terminal Calculator" / tcalc entry).
- Go 1.24+ (consistent with other apps/ projects).

## References
- Root `spec.md` — original living specification and iteration history.
- gostations (`apps/gostations`) — primary source for TUI patterns, lipgloss idioms, centering, flashes, Makefile, release hygiene, todo/ process (to be adopted later).
- galculator GTK screenshot — primary visual reference for the "large number + small mode row" display density.

See also:
- `docs/UI_DESIGN.md` (detailed integrated wide display row with leading base indicator + maximal width number, and keypad rendering notes)
- `docs/KEYBOARD.md` (key binding rationale and future hex entry considerations)

---
*Initialized during v0.1 skeleton work, 2026.*