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,104 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-02-28
+
+## Critical Issues
+
+**Empty Application Stub:**
+- Issue: The entire application is a bare "Hello, world!" stub with no functional implementation
+- Files: `src/main.rs`
+- Impact: No actual BBS markdown functionality exists; application is not usable
+- Fix approach: Implement core application logic for markdown bulletin board system functionality
+
+**Invalid Edition Specification:**
+- Issue: `Cargo.toml` specifies `edition = "2024"` which is not a valid Rust edition
+- Files: `Cargo.toml`
+- Impact: Build will fail or behave unexpectedly if edition validation is enforced; incorrect edition can affect language feature availability
+- Fix approach: Change to a valid edition: `2021` (latest stable) or `2018` if legacy support needed
+
+## Tech Debt
+
+**Minimal Dependency Management:**
+- Issue: Heavy dependency on ratatui (0.30.0) and its entire ecosystem for a stub application
+- Files: `Cargo.toml`
+- Impact: Unnecessary compiled binary size and build time for functionality that doesn't yet exist; approximately 60+ transitive dependencies for "Hello, world!"
+- Fix approach: Keep ratatui when actual TUI is implemented; document why ratatui was chosen early
+
+**No Error Handling:**
+- Issue: Application has no error handling, logging, or graceful failure modes
+- Files: `src/main.rs`
+- Impact: Crashes will be silent or unhelpful; no debugging information available
+- Fix approach: Implement structured error handling; consider using `anyhow` or `thiserror` crate (already available in dependencies)
+
+**No Architecture Documentation:**
+- Issue: Zero guidance on how BBS-MD should be structured or what features should be implemented
+- Files: Project root (missing design docs)
+- Impact: Development direction unclear; future contributors won't understand intent
+- Fix approach: Create architecture documentation, feature specification, and roadmap
+
+## Missing Critical Features
+
+**No TUI Implementation:**
+- What's missing: Terminal UI is imported (ratatui) but never used
+- Blocks: Cannot create/view/edit bulletin board content
+- Priority: High
+
+**No Data Persistence:**
+- What's missing: No markdown file handling, no storage mechanism
+- Blocks: Cannot persist BBS posts or configuration
+- Priority: High
+
+**No Input Processing:**
+- What's missing: Application ignores user input entirely
+- Blocks: Cannot interact with application
+- Priority: High
+
+## Test Coverage Gaps
+
+**Zero Testing:**
+- What's not tested: All functionality (or complete lack thereof)
+- Files: No test directory exists; `src/main.rs` has no tests
+- Risk: No confidence in correctness; refactoring will be dangerous
+- Priority: High
+
+## Scalability & Architecture Concerns
+
+**Monolithic Structure:**
+- Problem: Single main.rs file will quickly become unmaintainable as features are added
+- Current capacity: ~45 lines before severe maintainability issues
+- Scaling path: Create modular structure with separate modules for TUI layer, data layer, business logic
+
+**Dependency Organization:**
+- Problem: Entire ratatui ecosystem locked in at build time even when not used
+- Current capacity: 60+ transitive dependencies inflating binary
+- Scaling path: Feature-gate dependencies or defer dependency addition until features are implemented
+
+## Security Considerations
+
+**Unvalidated Input:**
+- Risk: Once input processing is added, no visible validation or sanitization strategy exists
+- Files: Will be implemented in future features
+- Current mitigation: None (application ignores input)
+- Recommendations: Plan input validation for markdown parsing; sanitize user-provided content if displayed; consider file path traversal protections if file loading is implemented
+
+**File System Access:**
+- Risk: Future markdown file handling could expose security issues (directory traversal, privilege escalation)
+- Files: Not yet implemented
+- Current mitigation: None
+- Recommendations: When implementing file I/O, enforce strict path validation; restrict operations to designated directories only
+
+## Dependencies at Risk
+
+**Edition Mismatch:**
+- Risk: Invalid edition specification may cause build failures or unexpected behavior in future toolchain versions
+- Impact: Application may not compile with newer Rust tools
+- Migration plan: Immediately fix to `edition = "2021"` to match stable toolchain
+
+**Tight Coupling to Ratatui:**
+- Risk: Early adoption of specific TUI framework before requirements are clear
+- Impact: Switching frameworks later will require significant refactoring
+- Migration plan: Encapsulate ratatui behind abstraction layer; consider generic TUI trait to allow future framework swaps
+
+---
+
+*Concerns audit: 2026-02-28*