commit f7e47dedee27b6e9ee649acc0daba7b6523b9156
parent 5f6a69b4b3b0274bfd933284403e65de213efa7f
Author: William Casarin <jb55@jb55.com>
Date: Mon, 21 Apr 2025 13:26:02 -0700
docs: add notedeck_columns readme
Signed-off-by: William Casarin <jb55@jb55.com>
Diffstat:
2 files changed, 247 insertions(+), 0 deletions(-)
diff --git a/crates/notedeck_columns/DEVELOPER.md b/crates/notedeck_columns/DEVELOPER.md
@@ -0,0 +1,194 @@
+# NoteDeck Columns - Developer Guide
+
+This document provides detailed information for developers who want to contribute to or understand the NoteDeck Columns codebase.
+
+## Project Structure
+
+The NoteDeck Columns codebase is organized as follows:
+
+```
+notedeck_columns
+├── src
+│ ├── ui # UI components and views
+│ │ ├── note # Note-related UI components (posts, replies, quotes)
+│ │ ├── column # Column UI components
+│ │ ├── search # Search functionality
+│ │ ├── profile # Profile views and editing
+│ │ └── ...
+│ ├── timeline # Timeline data structures and logic
+│ ├── storage # Persistence mechanisms
+│ ├── accounts # Account management
+│ ├── decks # Deck management
+│ ├── app.rs # Main application logic
+│ ├── app_creation.rs # Application initialization
+│ ├── route.rs # Routing system
+│ ├── nav.rs # Navigation logic
+│ └── ...
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Rust toolchain (latest stable recommended)
+- [nostrdb](https://github.com/damus-io/nostrdb) and its dependencies
+- egui and eframe
+
+### Building the Project
+
+1. Clone the repository:
+ ```bash
+ git clone https://github.com/damus-io/notedeck
+ cd notedeck
+ ```
+
+2. Build the project:
+ ```bash
+ cargo build --release
+ ```
+
+3. Run the application:
+ ```bash
+ cargo run --release
+ ```
+
+### Development Mode
+
+For development, you might want to run with debug symbols:
+
+```bash
+cargo run
+```
+
+## Core Concepts
+
+### Decks and Columns
+
+- **Deck**: A collection of columns that a user can switch between
+- **Column**: A view into a specific type of Nostr content (timeline, profile, etc.)
+
+### Timelines
+
+Timelines are a fundamental concept in NoteDeck Columns:
+
+- `Timeline`: Represents a stream of notes with filters and subscriptions
+- `TimelineKind`: Defines the type of timeline (Universe, Profile, Notifications, etc.)
+- `TimelineTab`: Filtered views of a timeline (e.g., Notes only vs. Notes & Replies)
+- `TimelineCache`: Caches timeline data for efficient access
+
+### Navigation and Routing
+
+- `Route`: Represents application navigation targets
+- `Router`: Manages the navigation stack for each column
+- `NavTitle`: Renders the title bar for navigation
+- `RenderNavAction`: Actions resulting from navigation events
+
+### UI Components
+
+The UI is built with egui and organized into components:
+
+- `PostView`, `PostReplyView`, `QuoteRepostView`: Note creation UI
+- `NoteView`: Displays Nostr notes
+- `ProfileView`: Displays and edits profiles
+- `TimelineView`: Renders timelines in columns
+- `DesktopSidePanel`: Side navigation panel
+
+## Key Implementation Details
+
+### Subscriptions and Realtime Updates
+
+NoteDeck Columns manages Nostr subscriptions and relay connections to provide realtime updates:
+
+- `MultiSubscriber`: Handles subscriptions to multiple relays
+- `Subscriptions`: Tracks application-wide subscriptions
+- `RelayPool`: Manages relay connections
+
+### Data Flow
+
+1. User actions create routes or trigger navigation
+2. Routes are mapped to timeline kinds or other UI views
+3. Timelines query nostrdb for notes matching their filters
+4. UI components render the note data
+5. Subscriptions keep the data updated in realtime
+
+### State Management
+
+State is managed at different levels:
+
+- `Damus`: Contains global application state
+- `DecksCache`: Holds deck and column configurations
+- `TimelineCache`: Caches timeline data
+- Various component-specific state structures
+
+## Testing
+
+Run the test suite:
+
+```bash
+cargo test
+```
+
+The codebase includes unit tests for critical components.
+
+## Common Tasks
+
+### Adding a New Column Type
+
+1. Add a new variant to `TimelineKind` enum in `timeline/kind.rs`
+2. Implement the necessary filter logic
+3. Update the serialization and parsing methods
+4. Add UI support in the AddColumn view
+
+### Adding UI Components
+
+1. Create a new Rust file in the appropriate ui directory
+2. Implement the component using egui
+3. Connect it to the routing system if needed
+
+### Implementing New Features
+
+When implementing new features:
+
+1. Start by understanding the relevant parts of the codebase
+2. Look for similar implementations as reference
+3. Follow the existing patterns for state management and UI components
+4. Add appropriate tests
+5. Update documentation
+
+## Troubleshooting
+
+### Common Issues
+
+- **Render Issues**: Check the egui-related code for layout problems
+- **Data Freshness**: Verify subscription and filter setup
+- **Performance**: Look for inefficient queries or rendering
+
+### Debugging
+
+- Use `tracing` macros (`debug!`, `info!`, `error!`) for logging
+- Run with `RUST_LOG=debug` for verbose output
+- Use `cargo expand` to inspect macro expansion
+
+## Architecture Decisions
+
+### Why egui?
+
+egui was chosen for its immediate mode rendering approach and Rust integration, making it well-suited for a responsive multi-column UI.
+
+### Why nostrdb?
+
+nostrdb provides high-performance local storage and querying for Nostr events, which is essential for a responsive client.
+
+### Timeline-centric Design
+
+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.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Run tests: `cargo test`
+5. Submit a pull request
+
+Please follow the existing code style and patterns.
diff --git a/crates/notedeck_columns/README.md b/crates/notedeck_columns/README.md
@@ -0,0 +1,53 @@
+# NoteDeck Columns
+
+A TweetDeck-style multi-column interface for Nostr built with Rust and egui.
+
+## Overview
+
+NoteDeck Columns is a specialized UI component of the NoteDeck Nostr client that provides a TweetDeck-inspired multi-column layout for browsing Nostr content. It allows users to create customizable "decks" with multiple columns, each showing different types of Nostr content (home timeline, notifications, hashtags, profiles, etc.).
+
+## Features
+
+- **Multi-column layout**: View different Nostr content types side by side
+- **Customizable decks**: Create and customize multiple decks for different use cases
+- **Column types**:
+ - Universe (global feed)
+ - Contact lists (follows)
+ - Profiles
+ - Notifications
+ - Hashtags
+ - Threads
+ - Search results
+ - Algorithmic feeds (e.g., last notes per pubkey)
+- **Interactions**: Post, reply, quote, and zap notes
+- **Media support**: View and upload images
+- **Multiple accounts**: Switch between multiple Nostr accounts
+
+## Getting Started
+
+NoteDeck Columns is part of the larger NoteDeck ecosystem. To use it:
+
+1. Clone the NoteDeck repository
+2. Build the project with Cargo
+3. Run NoteDeck and select the Columns interface
+
+See the [DEVELOPER.md](DEVELOPER.md) file for detailed setup instructions.
+
+## Architecture
+
+NoteDeck Columns is built using:
+
+- **Rust**: For performance and type safety
+- **egui**: For the UI rendering
+- **nostrdb**: For Nostr data storage and retrieval
+- **enostr**: For Nostr protocol communication
+
+The codebase is organized around the concept of timelines, views, and decks, with a column-based UI architecture.
+
+## Contributing
+
+Contributions are welcome! Please see [DEVELOPER.md](DEVELOPER.md) for information on how to set up your development environment and contribute to the project.
+
+## License
+
+NoteDeck Columns is licensed under the [GPL v3](LICENSE).
