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