bbs-md/.planning/codebase/STRUCTURE.md

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