# 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*