notedeck

One damus client to rule them all
git clone git://jb55.com/notedeck
Log | Files | Refs | README | LICENSE

DEVELOPER.md (5634B)


      1 # NoteDeck Columns - Developer Guide
      2 
      3 This document provides detailed information for developers who want to contribute to or understand the NoteDeck Columns codebase.
      4 
      5 ## Project Structure
      6 
      7 The NoteDeck Columns codebase is organized as follows:
      8 
      9 ```
     10 notedeck_columns
     11 ├── src
     12 │   ├── ui               # UI components and views
     13 │   │   ├── note         # Note-related UI components (posts, replies, quotes)
     14 │   │   ├── column       # Column UI components
     15 │   │   ├── search       # Search functionality
     16 │   │   ├── profile      # Profile views and editing
     17 │   │   └── ...
     18 │   ├── timeline         # Timeline data structures and logic
     19 │   ├── storage          # Persistence mechanisms
     20 │   ├── accounts         # Account management
     21 │   ├── decks            # Deck management
     22 │   ├── app.rs           # Main application logic
     23 │   ├── app_creation.rs  # Application initialization
     24 │   ├── route.rs         # Routing system
     25 │   ├── nav.rs           # Navigation logic
     26 │   └── ...
     27 ```
     28 
     29 ## Development Setup
     30 
     31 ### Prerequisites
     32 
     33 - Rust toolchain (latest stable recommended)
     34 - [nostrdb](https://github.com/damus-io/nostrdb) and its dependencies
     35 - egui and eframe
     36 
     37 ### Building the Project
     38 
     39 1. Clone the repository:
     40    ```bash
     41    git clone https://github.com/damus-io/notedeck
     42    cd notedeck
     43    ```
     44 
     45 2. Build the project:
     46    ```bash
     47    cargo build --release
     48    ```
     49 
     50 3. Run the application:
     51    ```bash
     52    cargo run --release
     53    ```
     54 
     55 ### Development Mode
     56 
     57 For development, you might want to run with debug symbols:
     58 
     59 ```bash
     60 cargo run
     61 ```
     62 
     63 ## Core Concepts
     64 
     65 ### Decks and Columns
     66 
     67 - **Deck**: A collection of columns that a user can switch between
     68 - **Column**: A view into a specific type of Nostr content (timeline, profile, etc.)
     69 
     70 ### Timelines
     71 
     72 Timelines are a fundamental concept in NoteDeck Columns:
     73 
     74 - `Timeline`: Represents a stream of notes with filters and subscriptions
     75 - `TimelineKind`: Defines the type of timeline (Universe, Profile, Notifications, etc.)
     76 - `TimelineTab`: Filtered views of a timeline (e.g., Notes only vs. Notes & Replies)
     77 - `TimelineCache`: Caches timeline data for efficient access
     78 
     79 ### Navigation and Routing
     80 
     81 - `Route`: Represents application navigation targets
     82 - `Router`: Manages the navigation stack for each column
     83 - `NavTitle`: Renders the title bar for navigation
     84 - `RenderNavAction`: Actions resulting from navigation events
     85 
     86 ### UI Components
     87 
     88 The UI is built with egui and organized into components:
     89 
     90 - `PostView`, `PostReplyView`, `QuoteRepostView`: Note creation UI
     91 - `NoteView`: Displays Nostr notes
     92 - `ProfileView`: Displays and edits profiles
     93 - `TimelineView`: Renders timelines in columns
     94 - `DesktopSidePanel`: Side navigation panel
     95 
     96 ## Key Implementation Details
     97 
     98 ### Subscriptions and Realtime Updates
     99 
    100 NoteDeck Columns manages Nostr subscriptions and relay connections to provide realtime updates:
    101 
    102 - `MultiSubscriber`: Handles subscriptions to multiple relays
    103 - `Subscriptions`: Tracks application-wide subscriptions
    104 - `RelayPool`: Manages relay connections
    105 
    106 ### Data Flow
    107 
    108 1. User actions create routes or trigger navigation
    109 2. Routes are mapped to timeline kinds or other UI views
    110 3. Timelines query nostrdb for notes matching their filters
    111 4. UI components render the note data
    112 5. Subscriptions keep the data updated in realtime
    113 
    114 ### State Management
    115 
    116 State is managed at different levels:
    117 
    118 - `Damus`: Contains global application state
    119 - `DecksCache`: Holds deck and column configurations
    120 - `TimelineCache`: Caches timeline data
    121 - Various component-specific state structures
    122 
    123 ## Testing
    124 
    125 Run the test suite:
    126 
    127 ```bash
    128 cargo test
    129 ```
    130 
    131 The codebase includes unit tests for critical components.
    132 
    133 ## Common Tasks
    134 
    135 ### Adding a New Column Type
    136 
    137 1. Add a new variant to `TimelineKind` enum in `timeline/kind.rs`
    138 2. Implement the necessary filter logic
    139 3. Update the serialization and parsing methods
    140 4. Add UI support in the AddColumn view
    141 
    142 ### Adding UI Components
    143 
    144 1. Create a new Rust file in the appropriate ui directory
    145 2. Implement the component using egui
    146 3. Connect it to the routing system if needed
    147 
    148 ### Implementing New Features
    149 
    150 When implementing new features:
    151 
    152 1. Start by understanding the relevant parts of the codebase
    153 2. Look for similar implementations as reference
    154 3. Follow the existing patterns for state management and UI components
    155 4. Add appropriate tests
    156 5. Update documentation
    157 
    158 ## Troubleshooting
    159 
    160 ### Common Issues
    161 
    162 - **Render Issues**: Check the egui-related code for layout problems
    163 - **Data Freshness**: Verify subscription and filter setup
    164 - **Performance**: Look for inefficient queries or rendering
    165 
    166 ### Debugging
    167 
    168 - Use `tracing` macros (`debug!`, `info!`, `error!`) for logging
    169 - Run with `RUST_LOG=debug` for verbose output
    170 - Use `cargo expand` to inspect macro expansion
    171 
    172 ## Architecture Decisions
    173 
    174 ### Why egui?
    175 
    176 egui was chosen for its immediate mode rendering approach and Rust integration, making it well-suited for a responsive multi-column UI.
    177 
    178 ### Why nostrdb?
    179 
    180 nostrdb provides high-performance local storage and querying for Nostr events, which is essential for a responsive client.
    181 
    182 ### Timeline-centric Design
    183 
    184 The codebase is structured around timelines because they provide a natural abstraction for the different types of Nostr content views needed in a column-based interface.
    185 
    186 ## Contributing
    187 
    188 1. Fork the repository
    189 2. Create a feature branch: `git checkout -b feature/my-feature`
    190 3. Make your changes
    191 4. Run tests: `cargo test`
    192 5. Submit a pull request
    193 
    194 Please follow the existing code style and patterns.