84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# P2P Chat Codebase Guide for Agents
|
|
|
|
This document outlines the development workflow, code style, and architectural patterns for the `p2p-chat` repository.
|
|
|
|
## 1. Build, Test, and Run Commands
|
|
|
|
### Basic Commands
|
|
* **Build**: `cargo build`
|
|
* **Run TUI (default)**: `cargo run`
|
|
* **Run GUI**: `cargo run -- --gui`
|
|
* **Check**: `cargo check`
|
|
* **Format**: `cargo fmt`
|
|
* **Lint**: `cargo clippy`
|
|
|
|
### Testing
|
|
* **Run all tests**: `cargo test`
|
|
* **Run a specific test**: `cargo test test_name`
|
|
* **Run tests with output**: `cargo test -- --nocapture`
|
|
|
|
### Debugging
|
|
* **Logs**:
|
|
* TUI mode logs to `p2p-chat.log` in the working directory.
|
|
* GUI mode logs to `stdout` (INFO/DEBUG) and `stderr` (WARN/ERROR).
|
|
* **Environment Variables**:
|
|
* `RUST_LOG`: Control logging levels (e.g., `RUST_LOG=p2p_chat=debug,iroh=info`).
|
|
|
|
## 2. Code Style & Architecture
|
|
|
|
### General Rust Guidelines
|
|
* **Edition**: Rust 2021.
|
|
* **Formatting**: Strictly follow `rustfmt`.
|
|
* **Error Handling**: Use `anyhow::Result` for application-level errors and main functions. Use specific `thiserror` enums for libraries/modules when precise error handling is required.
|
|
* **Async/Await**: The project is built on the `tokio` runtime. Use `async/await` for I/O-bound tasks.
|
|
|
|
### Project Structure
|
|
* `src/main.rs`: Application entry point, runtime setup, and main event loop.
|
|
* `src/app_logic.rs`: Core business logic (`AppLogic` struct). Handles network events and application commands. It is agnostic of the UI (TUI vs. GUI).
|
|
* `src/gui.rs`: Iced-based GUI implementation following the Elm architecture (Model-View-Update).
|
|
* `src/tui/`: Ratatui-based TUI implementation.
|
|
* `src/net/`: Networking layer wrapping `iroh` and `iroh-gossip`.
|
|
* `src/media/`: Audio/Video capture and playback (GStreamer, cpal, FFmpeg).
|
|
* `src/protocol/`: Data structures and serialization (`serde`, `bincode`, `postcard`) for network messages.
|
|
|
|
### Naming Conventions
|
|
* **Variables/Functions**: `snake_case`.
|
|
* **Types/Traits**: `CamelCase`.
|
|
* **Constants**: `SCREAMING_SNAKE_CASE`.
|
|
* **Files**: `snake_case.rs`.
|
|
|
|
### Architectural Patterns
|
|
1. **State Management**:
|
|
* `AppLogic` holds the source of truth for application state (`ChatState`, `MediaState`, `NetworkManager`, etc.).
|
|
* `FrontendState` is a simplified struct derived from `AppLogic` to pass data to the UI (GUI/TUI) for rendering.
|
|
* Do not put core business logic inside `gui.rs` or `tui/`.
|
|
|
|
2. **Concurrency**:
|
|
* Use `tokio::spawn` for background tasks.
|
|
* Use `tokio::sync::mpsc` channels for communicating between the UI and the backend logic.
|
|
* Use `tokio::sync::broadcast` for one-to-many event distribution (e.g., video frames).
|
|
* Use `Arc<Mutex<...>>` or `Arc<Atomic...>` for shared state when channels are insufficient, but prefer message passing.
|
|
|
|
3. **GUI (Iced)**:
|
|
* **Messages**: Define all UI interactions in the `Message` enum in `src/gui.rs`.
|
|
* **Update**: Handle `Message`s in the `update` function.
|
|
* **View**: Keep the `view` function strictly for rendering based on `self.state`.
|
|
* **Subscriptions**: Use `subscription` to listen for external events (e.g., backend state updates, video frames).
|
|
|
|
4. **Networking**:
|
|
* Based on `iroh` QUIC.
|
|
* Events are received in the main loop and processed by `AppLogic::handle_net_event`.
|
|
|
|
### Dependencies
|
|
* **Networking**: `iroh`, `iroh-gossip`.
|
|
* **Runtime**: `tokio`.
|
|
* **UI**: `iced` (GUI), `ratatui` + `crossterm` (TUI).
|
|
* **Media**: `gstreamer` (video capture), `cpal` (audio I/O), `ffmpeg-next` (video encoding).
|
|
|
|
### Common Tasks
|
|
* **Adding a new feature**:
|
|
1. Update `protocol/mod.rs` if it involves new network messages.
|
|
2. Update `AppLogic` to handle the logic.
|
|
3. Update `FrontendState` to expose data to the UI.
|
|
4. Update `gui.rs` and `tui/` to render the new state.
|