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,120 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-02-28
+
+## Directory Layout
+
+```
+bbs-md/
+├── src/                    # Rust source code
+│   └── main.rs            # Binary entry point and main application logic
+├── target/                # Build artifacts (generated)
+├── .git/                  # Git repository metadata
+├── .planning/             # Planning and documentation
+│   └── codebase/          # Architecture and structure docs
+├── Cargo.toml             # Rust package manifest
+├── Cargo.lock             # Dependency lock file
+└── .gitignore             # Git ignore rules
+```
+
+## Directory Purposes
+
+**src/**
+- Purpose: All Rust source code for the project
+- Contains: Rust modules and binary logic
+- Key files: `main.rs`
+
+**.planning/codebase/**
+- Purpose: Architecture and codebase analysis documents
+- Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md (as written)
+- Generated by: Codebase mapping process
+
+**target/**
+- Purpose: Build output directory (generated by Cargo)
+- Contains: Compiled binaries, dependencies, metadata
+- Generated: Yes
+- Committed: No (in .gitignore)
+
+## Key File Locations
+
+**Entry Points:**
+- `src/main.rs`: Main binary executable, contains fn main() and all current application logic
+
+**Configuration:**
+- `Cargo.toml`: Package metadata, dependencies, build configuration
+
+**Build Output:**
+- `Cargo.lock`: Locked dependency versions ensuring reproducible builds
+
+## Naming Conventions
+
+**Files:**
+- `main.rs`: Entry point for binary crate
+- `lib.rs`: Would be used for library crate (not present)
+- Module files: `module_name.rs` (snake_case)
+- Cargo files: `Cargo.toml`, `Cargo.lock`
+
+**Directories:**
+- `src/`: Source code directory (Rust convention)
+- `target/`: Build output (Cargo convention)
+- Module directories: `snake_case/` for organizing modules into subdirectories
+
+**Modules:**
+- Snake_case for module names in Rust
+- Single-word module names preferred for clarity
+
+## Where to Add New Code
+
+**New Feature:**
+- Primary code: `src/main.rs` until structure grows
+- Once > 300 lines: Extract to `src/feature_name.rs`, then `mod feature_name;` in main.rs
+- Tests: In same file with `#[cfg(test)]` module, or separate `src/feature_name_test.rs`
+
+**New Component/Module:**
+- Implementation: Create `src/module_name.rs`
+- Export in `src/main.rs` with `mod module_name;`
+- Public items: Use `pub` keyword and re-export in main if needed for internal use
+
+**Utilities:**
+- Shared helpers: Create `src/utils.rs` or `src/common.rs` for cross-cutting utilities
+- General-purpose: Keep in dedicated module, expose via public functions
+
+**UI Components:**
+- Ratatui-specific code: Keep in dedicated module like `src/ui.rs` or `src/widgets.rs`
+- Separate widget rendering logic from business logic
+- Re-export commonly used widgets from central location
+
+## Special Directories
+
+**target/:**
+- Purpose: Contains compiled binaries, intermediate build files, and dependencies
+- Generated: Yes
+- Committed: No
+
+**.git/:**
+- Purpose: Git repository metadata
+- Generated: Yes
+- Committed: Not applicable (part of .git directory)
+
+## Recommended Module Organization (As Project Grows)
+
+Once the codebase expands beyond the current single-file structure:
+
+```
+src/
+├── main.rs          # Binary entry, module declarations, main loop
+├── app.rs           # Application state and core logic
+├── ui/
+│   ├── mod.rs       # UI module exports
+│   ├── widgets.rs   # Custom widget definitions
+│   └── events.rs    # Event handling logic
+├── commands.rs      # Command/action definitions
+├── errors.rs        # Error types
+└── utils.rs         # Utility functions
+```
+
+This structure keeps concerns separated while maintaining minimal interdependencies.
+
+---
+
+*Structure analysis: 2026-02-28*