p2p-chat/AGENTS.md

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