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