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.