grain.social
chadtmiller.com
+159
README.md
+159
README.md
···
1
+
# Grain Social Monorepo
2
+
3
+
A photo-sharing social platform built on the [AT Protocol](https://atproto.com)
4
+
ecosystem, enabling users to create and share photo galleries in a decentralized
5
+
manner.
6
+
7
+
## Overview
8
+
9
+
Grain Social is a photo-sharing platform that leverages the AT Protocol for
10
+
decentralized identity and data persistence. The platform allows users to upload
11
+
photos, organize them into galleries, and share them with the AT Proto
12
+
community.
13
+
14
+
## Architecture
15
+
16
+
This monorepo contains multiple services that work together to provide the
17
+
complete Grain Social experience:
18
+
19
+
### 📱 [AppView](/appview)
20
+
21
+
The main frontend application built with Deno, TypeScript, and HTMX. Provides
22
+
the user interface for photo management, gallery creation, and social
23
+
interactions.
24
+
25
+
- **Tech Stack**: Deno, TypeScript, HTMX, Tailwind CSS, Preact
26
+
- **Features**: Photo uploads, gallery management, social features, custom
27
+
layouts
28
+
29
+
### 🖼️ [Darkroom](/darkroom)
30
+
31
+
A Rust-based service for generating composite images and gallery previews.
32
+
Handles image processing and screenshot generation for gallery sharing.
33
+
34
+
- **Tech Stack**: Rust, Axum, Tokio, Fantoccini
35
+
- **Features**: Composite image generation, HTML previews, screenshot capture
36
+
37
+
### 🔔 [Notifications](/notifications)
38
+
39
+
Notification service for handling real-time updates and user notifications
40
+
within the Grain Social ecosystem.
41
+
42
+
- **Tech Stack**: Deno, TypeScript
43
+
- **Features**: Real-time notifications, event processing
44
+
45
+
### 🏷️ [Labeler](/labeler)
46
+
47
+
Content labeling and moderation service implementing AT Protocol's labeling
48
+
standards for content moderation.
49
+
50
+
- **Tech Stack**: Deno, TypeScript
51
+
- **Features**: Content labeling, moderation tools
52
+
53
+
### 🌐 [Infrastructure](/nginx)
54
+
55
+
Nginx reverse proxy configuration for routing requests between services.
56
+
57
+
### 🗂️ [Local Infrastructure](/local-infra)
58
+
59
+
Docker Compose setup for local development including PDS, PLC directory, and
60
+
Jetstream services.
61
+
62
+
### 📝 [Lexicons](/lexicons)
63
+
64
+
AT Protocol lexicon definitions that define the data schemas and API contracts
65
+
used across the platform.
66
+
67
+
## Quick Start
68
+
69
+
### Prerequisites
70
+
71
+
- [Deno](https://deno.land/) 2.2.6+
72
+
- [Rust](https://rustup.rs/) 1.88+ (for Darkroom service)
73
+
- [Docker](https://docker.com/) (for local infrastructure)
74
+
- AT Protocol account ([Bluesky](https://bsky.app))
75
+
76
+
### Local Development
77
+
78
+
> **Note**: Local development documentation is work in progress and may be out
79
+
> of date. Please file an issue if you encounter problems.
80
+
81
+
1. **Clone the repository**
82
+
```bash
83
+
git clone https://github.com/grainsocial/grain.git
84
+
cd grain
85
+
```
86
+
87
+
2. **Set up local infrastructure** (optional)
88
+
```bash
89
+
# Add to /etc/hosts
90
+
echo "127.0.0.1 pds.dev.grain.social" | sudo tee -a /etc/hosts
91
+
echo "127.0.0.1 plc.dev.grain.social" | sudo tee -a /etc/hosts
92
+
echo "127.0.0.1 jetstream.dev.grain.social" | sudo tee -a /etc/hosts
93
+
94
+
# Start services
95
+
cd local-infra
96
+
docker compose up -d
97
+
```
98
+
99
+
3. **Start the AppView**
100
+
```bash
101
+
cd appview
102
+
cp .env.example .env # Configure your environment
103
+
deno task sync # Backfill network data
104
+
deno task dev # Start development server
105
+
```
106
+
107
+
4. **Start additional services** (in separate terminals)
108
+
```bash
109
+
# Darkroom service
110
+
cd darkroom
111
+
set -a; source .env; set +a; cargo run
112
+
113
+
# Notifications service
114
+
cd notifications
115
+
deno run -A main.ts
116
+
```
117
+
118
+
### Environment Configuration
119
+
120
+
Each service requires specific environment variables. Check the individual
121
+
service .env.example files for detailed configuration:
122
+
123
+
- [AppView](/appview/.env.example)
124
+
- [Darkroom](/darkroom/.env.example)
125
+
- [Labeler](/labeler/.env.example)
126
+
- [Notifications](/notifications/.env.example)
127
+
128
+
## Key Features
129
+
130
+
- **🖼️ Photo Management**: Upload, organize, and add metadata to photos
131
+
- **📚 Gallery Creation**: Create themed collections
132
+
- **👥 Social Features**: Follow users, favorite galleries, comment and interact
133
+
- **🎨 Custom Layouts**: Masonry and justified grid layout options
134
+
- **🔍 Discovery**: Explore galleries and users across the network
135
+
- **📱 Responsive Design**: Works across desktop and mobile devices
136
+
- **🌐 Decentralized**: Built on AT Protocol for user data ownership
137
+
138
+
## Development Workflow
139
+
140
+
1. **Code Generation**: Lexicon changes require running codegen in relevant
141
+
services
142
+
2. **Database Sync**: Use `deno task sync` to backfill AT Protocol data
143
+
3. **Deployment**: Services are containerized and ready for deployment
144
+
145
+
## Contributing
146
+
147
+
1. Fork the repository
148
+
2. Create a feature branch
149
+
3. Make your changes following the existing code conventions
150
+
4. Test your changes across relevant services
151
+
5. Submit a pull request
152
+
153
+
## License
154
+
155
+
MIT License - see [LICENSE](LICENSE) for details.
156
+
157
+
## Credits
158
+
159
+
Developed by Chad Miller
+5
darkroom/.env.example
+5
darkroom/.env.example
notifications/env.example
notifications/.env.example
notifications/env.example
notifications/.env.example