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 two-row display (large number + small current-base indicator) and 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.
• 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:
  • Large top area inside bordered panel for the number (tall padding + bold/high-visibility styling for "large font" weight).
  • 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 two-row display and keypad rendering notes)
• docs/KEYBOARD.md (key binding rationale and future hex entry considerations)

---

Initialized during v0.1 skeleton work, 2026.