mobile bluesky app made with flutter
lazurite.stormlightlabs.org/
mobile
bluesky
flutter
docs: comprehensive readme content
+127
-2
+127
-2
README.md
+127
-2
README.md
···
1
-
# Lazurite
1
+
<!-- markdownlint-disable MD041 -->
2
+
3
+
4
+
5
+
Lazurite is a cross-platform Bluesky client built with Flutter and Dart using Material You (M3) design.
6
+
7
+
## Features
8
+
9
+
### Home Feed
10
+
11
+
View your personal timeline with support for threads and media.
12
+
13
+
14
+
15
+
### Compose
16
+
17
+
Create new posts with rich text and media attachments. Supports replies and quoting.
18
+
19
+
20
+
21
+
### Search
22
+
23
+
Discover people and posts across the Bluesky network.
24
+
25
+
26
+
27
+
### Profile
28
+
29
+
View detailed actor profiles, including their feed and metadata.
30
+
31
+
32
+
33
+
### Developer Tools
34
+
35
+
Built-in logs and developer utilities for exploring the AT Protocol.
36
+
37
+
38
+
39
+
### Offline Support & Drafts
40
+
41
+
Local-only drafts and caching powered by Drift (SQLite).
42
+
43
+
- **Drafts:** Save posts locally and publish later.
44
+
- **Search History:** Persisted local search history.
45
+
- **Saved Feeds:** Manage and pin your favorite feeds.
46
+
47
+
## Architecture
48
+
49
+
### Stack
50
+
51
+
- **Framework:** Flutter (M3)
52
+
- **State Management:** `flutter_bloc`
53
+
- **Database:** Drift (SQLite)
54
+
- **Networking:** Dio + `atproto`/`bluesky` packages
55
+
- **Navigation:** `go_router`
56
+
- **Data Serialization:** `freezed` + `json_serializable`
57
+
58
+
### Directory Structure
59
+
60
+
The project follows a feature-first architecture layered with a core module:
61
+
62
+
- `lib/core/`: Shared infrastructure, database, router, and themes.
63
+
- `lib/features/`: Feature-specific logic (Auth, Feed, Search, Profile, etc.).
64
+
- `<feature>/bloc/`: Business logic components.
65
+
- `<feature>/presentation/`: UI screens and widgets.
66
+
- `<feature>/data/`: (Optional) Feature-specific repositories or models.
2
67
3
-
Cross-platform mobile BlueSky client.
68
+
### Data Flow
69
+
70
+
- **Network:** Authenticated requests are routed through user PDS; public reads use the public AppView.
71
+
- **Database:** Drift manages local persistence for accounts, cached profiles/posts, settings, and drafts.
72
+
73
+
### Routing
74
+
75
+
Lazurite uses `StatefulShellRoute` for persistent bottom navigation.
76
+
77
+
| Path | Description |
78
+
| ----------- | ------------------------------ |
79
+
| `/login` | Authentication gateway |
80
+
| `/` | Home Feed tab |
81
+
| `/search` | Search tab |
82
+
| `/profile` | Current user profile tab |
83
+
| `/settings` | Global settings |
84
+
| `/compose` | Root-level modal for new posts |
85
+
86
+
## Local Development
87
+
88
+
Use `just` for common tasks:
89
+
90
+
- `just format` - Runs `dart format`
91
+
- `just lint` - Proxies `flutter analyze`
92
+
- `just test` - Executes the `flutter test` suite
93
+
- `just gen` - Triggers `build_runner` for code generation
94
+
- `just check` - Runs format, lint, and tests in sequence
95
+
96
+
For a quick start:
97
+
98
+
```sh
99
+
flutter pub get
100
+
just gen
101
+
flutter run
102
+
```
103
+
104
+
## Database Schema
105
+
106
+
Powered by **Drift**, the following tables are currently implemented:
107
+
108
+
| Table | Purpose |
109
+
| ----------------- | ---------------------------------------------------------------- |
110
+
| `accounts` | Local storage for session and auth tokens (DID, handle, service) |
111
+
| `cached_profiles` | Cached profile metadata to reduce network calls |
112
+
| `cached_posts` | Cached post content for offline viewing |
113
+
| `saved_feeds` | Locally Managed feed preferences |
114
+
| `search_history` | Persistent query history |
115
+
| `drafts` | Offline-first post drafting with media support |
116
+
| `settings` | Key-value application configuration |
117
+
118
+
## References
119
+
120
+
- [Bluesky API Documentation](https://docs.bsky.app/)
121
+
- [AT Protocol Specification](https://atproto.com/)
122
+
- [Flutter Documentation](https://flutter.dev/docs)
123
+
124
+
## Credits
125
+
126
+
- Typography inspiration from [Anisota](https://anisota.net/) by [Dame.is](https://dame.is).
127
+
- Inspired by [Witchsky](https://witchsky.app/).
128
+
- DevTools (AT Protocol Explorer) inspiration from [pdsls](https://pds.ls/)
docs/images/hero.png
docs/images/hero.png
This is a binary file and will not be displayed.