Highly ambitious ATProtocol AppView service and sdks
add readme, update gitignore, add env examples
+158
+147
README.md
+147
README.md
···
1
+
# Slices Social - A social app for sharing/creating AT Protocol Appviews
2
+
3
+
Slices Social is an AT Protocol appview that allows users to create and share
4
+
slices (appviews).
5
+
6
+
## Architecture
7
+
8
+
- **API** (`/api`) - Rust backend with AT Protocol integration, PostgreSQL
9
+
database, and dynamic XRPC handlers
10
+
- **Frontend** (`/frontend`) - Deno server-side rendered application with OAuth
11
+
authentication
12
+
13
+
## ✅ Completed Features
14
+
15
+
### Core Infrastructure
16
+
17
+
- [x] AT Protocol OAuth integration with AIP server
18
+
- [x] PostgreSQL database with slice-aware queries
19
+
- [x] Docker containerization with Nix flakes
20
+
- [x] Production deployment pipeline
21
+
22
+
### Slice Management
23
+
24
+
- [x] Create and manage slice records
25
+
- [x] Define custom lexicons for slices (appviews)
26
+
- [x] Slice-specific data filtering
27
+
- [x] Slice statistics (records, collections, actors)
28
+
29
+
### Data Synchronization
30
+
31
+
- [x] Bulk sync from AT Protocol repositories based on domain specific lexicons
32
+
- [x] Collection-specific sync with repo filtering
33
+
- [x] Indexing of records into local database
34
+
- [x] Slice-aware record filtering during sync
35
+
36
+
### TypeScript Client Generation
37
+
38
+
- [x] Dynamic TypeScript client generation from lexicons
39
+
- [x] Nested collection structure (e.g.,
40
+
`client.social.slices.slice.listRecords()`)
41
+
- [x] CRUD operations (create, read, update, delete)
42
+
- [x] OAuth client with PKCE authentication flow
43
+
- [x] Slice-aware collection operations
44
+
- [x] Optional authentication for read-only operations (e.g., listRecords,
45
+
getRecord)
46
+
47
+
### Frontend
48
+
49
+
- [x] Server-side rendered pages with HTMX
50
+
- [x] User authentication and session management
51
+
- [x] Slice overview with index statistics
52
+
- [x] Records browser with collection/author filtering
53
+
- [x] Sync interface with collection prefilling from lexicons
54
+
- [x] Settings page to edit profile
55
+
- [x] Encrypted cookie-based sessions
56
+
57
+
### API Endpoints
58
+
59
+
- [x] `/xrpc/social.slices.slice.sync` - Bulk synchronization
60
+
- [x] `/xrpc/social.slices.slice.stats` - Slice statistics
61
+
- [x] `/xrpc/social.slices.slice.records` - Slice records with filtering
62
+
- [x] `/xrpc/social.slices.slice.codegen` - Client code generation (currently
63
+
TypeScript only, but designed for extensibility)
64
+
- [x] Dynamic collection XRPC endpoints (`*.list`, `*.get`, `*.create`, etc.)
65
+
- [x] OAuth endpoints for authentication flow
66
+
67
+
## 🚧 In Progress/Next Up
68
+
69
+
- [ ] Connect to Jetstream
70
+
- [ ] Add search and filtering functionality to records browser, and generated
71
+
client
72
+
- [ ] Support more complex lexicon types (e.g., unions, arrays, refs)
73
+
- [ ] Lexicon validation
74
+
- [ ] Lexicon verification
75
+
- [ ] SDK examples and tutorials, implement Statusphere Slice
76
+
- [ ] Pagination for large record sets, maybe even a table view would be cool
77
+
- [ ] Slice timeline and user profile pages
78
+
- [ ] Display xprc docs for dynamic endpoints (looking at
79
+
[Scalar](https://github.com/scalar/scalar))
80
+
81
+
## ❌ The Future
82
+
83
+
- [ ] Integrated labeler service for basic moderation
84
+
- [ ] Auto view hydration strategies, maybe configureable in the UI
85
+
- [ ] Add pre-defined lexicons straight from Lexicon Community or other sources
86
+
- [ ] Support more languages for client code generation (e.g., Python,
87
+
Flutter/Dart, Swift)
88
+
- [ ] Integrate/interop with various Microcosm services
89
+
- [ ] Cli tool for codegen and other utilities
90
+
- [ ] Background job processing queue for syncs
91
+
- [ ] Rate limiting and API quotas
92
+
- [ ] API docs
93
+
- [ ] Appview bug tracking, waitlists, feature flags, analytics, etc.
94
+
- [ ] Fork a slice!
95
+
- [ ] Strategies for managing/migrating lexicon changes over time
96
+
97
+
## 🛠️ Development
98
+
99
+
### Prerequisites
100
+
101
+
- Nix with flakes enabled (not required, used for deployment)
102
+
- Docker
103
+
- PostgreSQL
104
+
105
+
### Getting Started
106
+
107
+
```bash
108
+
# Start API development
109
+
cd api
110
+
cargo run
111
+
112
+
# Start frontend development
113
+
cd frontend
114
+
deno task dev
115
+
```
116
+
117
+
### Useful Scripts
118
+
119
+
- `api/scripts/test_sync.sh` - Test local sync endpoint (pre-seed all slices
120
+
from the atmosphere)
121
+
- `frontend/scripts/register-oauth-client.sh` - Register OAuth client with AIP
122
+
123
+
## 🚀 Deployment
124
+
125
+
The service is deployed using Nix-built Docker containers with:
126
+
127
+
- Fly.io for hosting (move to Upscale?)
128
+
- PostgreSQL for data storage
129
+
- Environment-based configuration
130
+
131
+
## 📝 Environment Variables
132
+
133
+
### API
134
+
135
+
- `DATABASE_URL` - PostgreSQL connection string
136
+
- `AUTH_BASE_URL` - AIP OAuth service URL
137
+
- `PORT` - Server port (default: 3000)
138
+
139
+
### Frontend
140
+
141
+
- `OAUTH_CLIENT_ID` - OAuth application client ID
142
+
- `OAUTH_CLIENT_SECRET` - OAuth application client secret
143
+
- `OAUTH_REDIRECT_URI` - OAuth callback URL
144
+
- `OAUTH_AIP_BASE_URL` - AIP OAuth service URL
145
+
- `SESSION_ENCRYPTION_KEY` - Session cookie encryption key
146
+
- `API_URL` - Backend API base URL
147
+
- `SLICE_URI` - Filters collection based queries by slice
+3
api/.env.example
+3
api/.env.example
+7
frontend/.env.example
+7
frontend/.env.example
···
1
+
OAUTH_CLIENT_ID="your-oauth-client-id"
2
+
OAUTH_CLIENT_SECRET="your-oauth-client-secret"
3
+
OAUTH_REDIRECT_URI="http://localhost:8080/oauth/callback"
4
+
OAUTH_AIP_BASE_URL="https://your-domain.com"
5
+
SESSION_ENCRYPTION_KEY="your-base64-encoded-encryption-key"
6
+
API_URL="http://localhost:3000"
7
+
SLICE_URI="at://did:plc:bcgltzqazw5tb6k2g3ttenbj/social.slices.slice/3lwzmbjpqxk2q"