1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
- **Development server**: `bun run dev` - Starts Vite dev server on http://localhost:5173
- **Build**: `bun run build` - TypeScript compilation followed by Vite production build
- **Linting**: `bun run lint` - Run ESLint on all files
- **Preview build**: `bun run preview` - Preview production build locally
- **Type checking**: `tsc -b` - Run TypeScript compiler to check types
## Architecture
This is a React TypeScript frontend for an Urbit application called Nostrill, which appears to integrate Nostr (decentralized social protocol) with Urbit (personal server).
### Key Technologies
- **React 19** with TypeScript
- **Vite** for build tooling
- **Zustand** for global state management
- **TanStack Query** for server state and data fetching
- **Wouter** for routing
- **Urbit API** integration via custom packages in parent directories
### Project Structure
```
src/
├── components/ # UI components organized by feature
│ ├── composer/ # Post composition UI
│ ├── feed/ # Feed display components
│ ├── layout/ # Layout components (Sidebar, etc.)
│ ├── modals/ # Modal dialogs
│ └── post/ # Post display components and wrappers
├── logic/ # Business logic and utilities
│ ├── api.ts # Urbit connection setup
│ ├── nostrill.ts # Nostrill-specific logic
│ └── requests/ # API request handlers
├── pages/ # Route components (Feed, User, Settings)
├── state/ # Zustand store (state.ts)
├── styles/ # Styling and theming
├── types/ # TypeScript type definitions
└── Router.tsx # Main routing configuration
```
### State Management
The application uses Zustand for state management (`src/state/state.ts`):
- Manages Urbit connection via `IO` class
- Stores Nostr events, user profiles, relay data
- Handles following/followers relationships
- Manages UI state (modals, composer data)
### Urbit Integration
- Connection established via `src/logic/api.ts`
- Uses Urbit Airlock/SSE for real-time updates
- Interacts with the `nostrill` desk on the Urbit ship
- Local packages used from parent directories:
- `urbit-api`: HTTP API client
- `urbit-ob`: Urbit ID utilities
- `urbit-sigils`: Visual ship identifiers
### Path Aliases
The project uses `@` alias for `src/` directory (configured in vite.config.ts).
### Key Data Flows
1. **Initialization**: App.tsx → state.init() → api.start() → Urbit connection
2. **State Updates**: Urbit SSE → IO subscriptions → Zustand store updates
3. **User Actions**: Components → IO methods → Urbit pokes/scries → State updates
## Future Feature Ideas
### 1. Real-time Notifications System
- Toast notifications for new follows, mentions, access requests
- Bell icon with notification count in sidebar
- Notification center/inbox with activity history
- Sound/desktop notifications
- Mark as read/unread functionality
### 2. Advanced Post Composer
- Rich text editor with markdown support
- Image/media upload and preview
- Draft saving (auto-save as you type)
- Post scheduling for later
- Character count and formatting preview
- Emoji picker integration
- @mentions with autocomplete
### 3. Search & Discovery
- Global search for posts, users, hashtags
- Trending topics/hashtags
- User discovery with suggested follows
- Advanced filters (date range, user, content type)
- Search history and saved searches
### 4. Bookmarking System
- Save posts for later reading
- Organize bookmarks into collections/folders
- Search through saved posts
- Export bookmarks
- Private notes on bookmarks
### 5. Post Analytics Dashboard
- View engagement metrics on your posts
- Follower growth over time graphs
- Most popular posts
- Activity heatmap
- Engagement rate tracking
- Best posting times analysis
### 6. Direct Messaging
- Private messaging between users
- Encrypted DMs via Nostr/Urbit protocols
- Message threads and history
- File sharing in DMs
- Read receipts
- Typing indicators
### 7. Additional Features to Consider
- User groups/communities
- Content moderation tools
- Multi-account support
- Import/export data
- PWA support for mobile
- Keyboard shortcuts
- Custom themes creator
- Language translations
|
