Skip to content

CLAUDE.md

Latest commit

 

History

History
143 lines (108 loc) · 4.63 KB

CLAUDE.md

File metadata and controls

143 lines (108 loc) · 4.63 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Read ./CONVENTIONS.md file.

Read SECURITY.md before changing security-sensitive HTTP routes, session authorization, private messages, credential-bearing responses, or user-controlled media. Before driving Rostra through a browser, also use the preview-rostra skill.

This project uses the Linked Specs convention; consult the linked-specs skill before working with specs or governed code. For web UI functionality/security tradeoffs, also read REQ-ui-functionality-security.

Project Overview

Rostra is a p2p (friend-to-friend) social network built in Rust. It uses a lightweight event DAG system where all data is propagated as signed Events, enabling decentralized social networking with sovereign identities and multi-device support.

Architecture

  • Core principle: All data propagates as cryptographically signed Events forming a DAG structure
  • Network layer: Uses Pkarr for distributed identity/naming and iroh-net for p2p transport
  • UI: Web-based interface using Axum, Maud, Alpine, and alpine-ajax
  • Storage: Local database for tracking events and content

Project Structure

  • crates/rostra-core - Core domain types used across the project
  • crates/rostra-client-db - Database for tracking all events
  • crates/rostra-web-ui - Default web-based UI (Axum + Maud + Alpine/alpine-ajax)
  • crates/rostra-client - Client implementation (includes shared RPC utilities in util::rpc)
  • crates/rostra-p2p - P2P networking layer
  • crates/rostra-p2p-api - P2P API definitions
  • crates/rostra-util-* - Various utility crates
  • crates/bots/ - Bot implementations

Development Commands

Building and Testing

# Build the project
cargo build
# or: just build

# Run tests
cargo nextest run
# or: just test

# Check code (faster than build)
cargo check
# or: just check

Code Quality

# Run all pre-PR checks (lint + clippy + test)
just final-check

# Format code
just format  # runs cargo fmt + nixfmt

# Run lints (pre-commit hook)
just lint

# Run clippy
just clippy

# Fix clippy issues
just clippy-fix

Running the Application

# Run web UI in production mode
cargo run --release web-ui

# Development mode with hot reload on port 2345
just dev

# Development on custom port
just dev 3000

Testing Individual Components

# Test specific crate
cargo test -p rostra-core

# Test with logging
RUST_LOG=debug cargo test

# Run specific test
cargo test test_name

Web UI Architecture

The web UI (crates/rostra-web-ui) uses:

  • Axum for the web server framework
  • Maud for HTML templating
  • Alpine + alpine-ajax for progressive enhancement
  • Tower middleware for sessions, cookies, compression
  • Server-rendered HTML as the primary interaction architecture

Key web UI files:

  • src/routes/ - Route handlers for different pages
  • src/lib.rs - Main application setup
  • Routes include: timeline, post, profile, avatar, etc.

Development Notes

  • Uses Rust 2024 edition
  • Workspace-based multi-crate structure
  • Structured logging with tracing
  • No inline mods - use standalone modules
  • Supports multi-device sync through event DAG merging

Web UI Conventions

  • Follow DESIGN-server-rendered-hypermedia: changed workflows must work through ordinary HTTP without JavaScript. Alpine is progressive enhancement; /unlock Create Account is the documented browser-local exception that fills the login form without submitting.
  • Apply REQ-ui-functionality-security: the no-JavaScript baseline is not a ban on required first-party browser conveniences, and implementation mechanisms do not become stakeholder mandates.
  • For keyboard shortcuts that trigger requestSubmit(), always use keyup (not keydown). keydown fires repeatedly with key auto-repeat, which can cause duplicate form submissions and race conditions in alpine-ajax.
  • Keep authenticated Settings recovery export server-rendered, session-scoped, unavailable to read-only sessions, and protected by the sensitive response headers in routes/recovery.rs. Its recovery phrase uses a masked read-only field and a conventional copy control; do not add reveal dialogs or confirmation steps.
  • /unlock Create Account may expose a generated credential only in a secure response with those sensitive headers. It fills editable login fields without submitting or navigating.