121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# 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*
|