docs: map existing codebase

2026-02-28 20:12:08 +01:00
commit 7f1a4ce1f1
7 changed files with 1049 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Architecture
+
+**Analysis Date:** 2026-02-28
+
+## Pattern Overview
+
+**Overall:** Single-Binary CLI/TUI Application (Rust)
+
+**Key Characteristics:**
+- Monolithic Rust binary using Ratatui for terminal UI
+- Minimal dependency footprint (only Ratatui as external dependency)
+- Single entry point with main function
+- Early-stage project with foundational structure only
+
+## Layers
+
+**Presentation Layer:**
+- Purpose: Terminal user interface rendering and interaction
+- Location: `src/main.rs` (currently)
+- Contains: TUI initialization, event handling, widget rendering
+- Depends on: Ratatui framework
+- Used by: End users through terminal
+
+**Business Logic Layer:**
+- Purpose: Core application functionality
+- Location: TBD - not yet implemented
+- Contains: Data processing, command handling, state management
+- Depends on: None currently defined
+- Used by: Presentation layer
+
+**Data Layer:**
+- Purpose: Data persistence and retrieval
+- Location: TBD - not yet implemented
+- Contains: File I/O, caching, serialization
+- Depends on: Standard library (File, IO)
+- Used by: Business logic layer
+
+## Data Flow
+
+**Typical User Interaction Flow:**
+
+1. Terminal input captured by Ratatui event handling
+2. User action (keyboard/mouse) parsed into application command
+3. Command dispatched to business logic handler
+4. Handler processes request, potentially reads/writes data
+5. State updated based on result
+6. UI re-rendered with new state in next frame
+
+**State Management:**
+- Single application state entity (not yet defined)
+- Immutable state passed to rendering function
+- Ratatui handles incremental screen updates
+
+## Key Abstractions
+
+**Terminal User Interface (TUI):**
+- Purpose: Encapsulate all terminal rendering and input handling
+- Examples: `src/main.rs` (current single module)
+- Pattern: React-like paradigm via Ratatui (state -> render)
+
+**Application Command/Action:**
+- Purpose: Abstract user intentions from input events
+- Examples: Not yet implemented
+- Pattern: Enum-based command pattern expected
+
+## Entry Points
+
+**Binary Entry:**
+- Location: `src/main.rs`
+- Triggers: `cargo run` or binary execution
+- Responsibilities:
+  - Initialize Ratatui terminal
+  - Set up event loop
+  - Handle application lifecycle
+  - Render UI each frame
+  - Currently: Placeholder with "Hello, world!" output
+
+## Error Handling
+
+**Strategy:** Not yet defined
+
+**Patterns:**
+- Ratatui provides Result types for I/O operations
+- Expected approach: Result-based error propagation using ? operator
+- Terminal restoration should be ensured on panic (Ratatui provides Drop impl)
+
+## Cross-Cutting Concerns
+
+**Logging:** Not yet implemented. Standard approach would use `log` crate or println! macros during development.
+
+**Validation:** Not yet implemented. Expected in business logic layer once commands are defined.
+
+**Terminal State:** Ratatui manages terminal state (raw mode, cursor visibility, etc.). Must ensure proper cleanup on application exit.
+
+---
+
+*Architecture analysis: 2026-02-28*