smokesignal.events
A decentralized event management and credentialing system built on atproto.
1# Acudo
2
3A decentralized event management and credentialing system built on the AT Protocol, combining traditional ticketing infrastructure with cryptographically-verifiable badges and RSVPs. Acudo bridges Web 2.0 ticketing platforms like Tito with the emerging decentralized social web, enabling event organizers to issue portable, verifiable credentials to attendees.
4
5## Overview
6
7Acudo represents a novel approach to event management in the decentralized web era. By leveraging the AT Protocol (the foundation of Bluesky), it transforms traditional event RSVPs and tickets into cryptographically-signed records that attendees own and control. These records live in the attendee's personal data server (PDS), making them portable across applications and verifiable by third parties.
8
9### Key Innovations
10
11- **Decentralized Credentials**: Event attendance becomes a verifiable credential that attendees can showcase across AT Protocol-compatible applications
12- **Badge Award System**: Sophisticated rule engine that automatically awards badges based on ticket purchases, enabling gamification and special recognition
13- **Cryptographic Trust**: All records are signed by event organizers, providing cryptographic proof of authenticity
14- **Identity Resolution**: Advanced caching layer for DID document resolution, optimizing performance while maintaining decentralized principles
15- **Hybrid Architecture**: Seamlessly integrates traditional ticketing (Tito) with decentralized identity and storage
16
17## Technical Architecture
18
19### Core Technologies
20
21- **Rust & Axum**: High-performance async web framework providing sub-millisecond response times
22- **AT Protocol SDK**: Full integration with atproto-* crates for identity, OAuth, and record management
23- **PostgreSQL**: JSONB-powered storage with GIN indexing for efficient querying of AT Protocol records
24- **Minijinja Templates**: Server-side rendering with Jinja2-compatible templating
25- **Identity Caching**: LRU cache with configurable TTL for DID document resolution
26
27### AT Protocol Integration
28
29Acudo deeply integrates with the AT Protocol ecosystem:
30
311. **OAuth Flows**: Supports both PDS OAuth and AT Protocol Improvement Proposal (AIP) OAuth backends
322. **DID Resolution**: Resolves decentralized identifiers through PLC and Web DID methods
333. **Record Creation**: Creates lexicon-compliant records with proper signatures
344. **Jetstream Consumer**: Real-time event processing from the AT Protocol firehose
355. **Cryptographic Verification**: All records are verified using atproto_record::signature
36
37### Data Flow
38
39```
40User → OAuth Login → Ticket Purchase (Tito) → Rule Evaluation →
41Record Creation → Signature → AT Protocol PDS → User's Repository
42```
43
44The system maintains local copies for performance while ensuring the user's PDS remains the source of truth.
45
46## Badge Award System
47
48The badge system uses a JSON Logic-based rule engine (powered by `datalogic-rs`) to evaluate ticket purchases and determine which AT Protocol records (RSVPs and badge awards) should be created:
49
50### Rule Structure
51
52```json
53{
54 "aturis": [
55 "at://did:plc:cbkjy5n7bk3ax2wplmtjofq2/community.lexicon.calendar.event/3luzkrwivzm2a",
56 "at://did:web:oauth-masterclass.atproto.camp/community.lexicon.calendar.event/3lwtxdryiw22b"
57 ],
58 "create": {
59 "and": [
60 {
61 "==": [
62 "Oct 4 Individual Seat (Early Bird)",
63 {
64 "val": "ticket_type"
65 }
66 ]
67 },
68 {
69 "<": [
70 {
71 "val": "purchase_at"
72 },
73 "2025-08-25T00:00:00Z"
74 ]
75 }
76 ]
77 },
78 "signature_extra": {}
79}
80```
81
82Rules can evaluate:
83- Ticket type and pricing tiers
84- Purchase timing (early bird, last minute)
85- Custom metadata from ticketing platforms
86- Complex logical combinations (AND, OR, NOT)
87
88The `aturis` field specifies which AT Protocol records to create when the rule evaluates to true:
89- Event RSVPs: `at://did:plc:*/community.lexicon.calendar.event/*`
90- Badge awards: `at://did:plc:*/community.lexicon.badge.award/*`
91
92### Security Model
93
94All badges and RSVPs are cryptographically signed by the event organizer's private key. The verification process:
95
961. Records are generated server-side with issuer signatures
972. Client receives pre-signed records for review
983. User selects which records to create
994. Server verifies signatures before submission
1005. Records are written to user's PDS repository
101
102This ensures that badges cannot be forged and provides cryptographic proof of the issuer's authorization.
103
104## Getting Started
105
106### Prerequisites
107
108- Rust 1.89+ (2024 edition)
109- PostgreSQL 15+
110- AT Protocol PDS or OAuth server access
111- Environment variables configured (see Configuration section)
112
113### Installation
114
1151. Clone the repository
1162. Set up PostgreSQL database
1173. Configure environment variables (see Configuration)
1184. Run database migrations: `sqlx migrate run`
1195. Build and run: `cargo run --release`
120
121## Configuration
122
123### Core Configuration
124
125```bash
126# AT Protocol Configuration
127EXTERNAL_BASE=your-event.example.com
128ISSUER_DID=did:plc:abc123def456
129ISSUER_PRIVATE_KEY=did:key:z6Mk...
130EVENT_ATURIS=main=at://did:plc:abc/event.calendar/record-key
131
132# Database
133DATABASE_URL=postgres://user:pass@localhost/acudo
134
135# OAuth Backend Selection
136OAUTH_BACKEND=pds # or "aip" for AT Protocol Improvement Proposal OAuth
137```
138
139### Performance Tuning
140
141```bash
142# Identity Cache Configuration
143IDENTITY_CACHE_SIZE=500 # Max cached DID documents
144IDENTITY_CACHE_TTL_MINUTES=10 # Cache TTL
145```
146
147### OAuth Backend Configuration
148
149#### PDS OAuth
150```bash
151SIGNING_KEYS=did:key:z6Mk...;did:key:z6Mk... # Semicolon-separated
152PLC_HOSTNAME=plc.directory
153```
154
155#### AIP OAuth
156```bash
157AIP_SERVER=https://auth.example.com
158AIP_CLIENT_ID=your_client_id
159AIP_CLIENT_SECRET=your_client_secret
160```
161
162### Admin Configuration
163
164```bash
165# Admin Access (semicolon-separated DIDs)
166ADMIN_DIDS=did:plc:admin1;did:plc:admin2
167
168# Tito Integration
169TITO_WEBHOOK_SECRET=webhook_secret_from_tito
170```
171
172## Admin Interface
173
174Acudo includes a comprehensive admin interface for event organizers:
175
176### Features
177
178- **Badge Rule Management**: Create and manage JSON Logic rules for automatic badge awards
179- **Event Management**: Import and manage events with JSON field search
180- **Data Viewing**: Browse DID documents, RSVPs, tickets with pagination
181- **Real-time Monitoring**: View system activity and badge award statistics
182
183### Access Control
184
185Admin access is controlled via DID-based authentication. Only DIDs listed in `ADMIN_DIDS` environment variable can access admin features. The system returns 404 for unauthorized users to prevent discovery of admin endpoints.
186
187## API Endpoints
188
189### Public Endpoints
190- `GET /` - Event homepage with activity feed
191- `GET /tickets` - Ticket management interface (requires auth)
192- `POST /records/create` - Batch record creation with signature verification
193- `GET /auth/login` - OAuth login initiation
194- `GET /auth/callback` - OAuth callback handler
195- `POST /api/webhooks/tito` - Tito webhook receiver
196
197### Well-Known Endpoints
198- `GET /.well-known/did.json` - did:web resolution
199- `GET /.well-known/atproto-did` - AT Protocol DID resolution
200- `GET /oauth/client-metadata.json` - OAuth client metadata
201- `GET /.well-known/jwks.json` - JSON Web Key Set
202
203## Storage Architecture
204
205### Storage Layers
206
2071. **Identity Storage**: DID documents with pagination support
2082. **OAuth Storage**: Request tokens with automatic expiration
2093. **Event Storage**: AT Protocol event records with JSON search
2104. **Ticket Storage**: Integration with external ticketing systems
2115. **Badge Storage**: Award records and rule definitions
2126. **RSVP Storage**: Signed attendance records
213
214### Performance Optimizations
215
216- **Connection Pooling**: Configurable pool sizes for database connections
217- **Identity Caching**: LRU cache reduces DID resolution latency by 90%
218- **JSON Indexing**: GIN indexes on JSONB columns for sub-millisecond queries
219- **Batch Operations**: Bulk record creation reduces round trips
220- **Async Everything**: Tokio-based async runtime for high concurrency
221
222## Development
223
224### Testing
225
226The codebase includes comprehensive test coverage using SQLx's test framework:
227
228```bash
229# Run all tests
230cargo test
231
232# Run specific test suites
233cargo test storage::event # Event storage tests
234cargo test identity_cache # Identity cache tests
235cargo test badges # Badge rule engine tests
236
237# Run with test output
238cargo test -- --nocapture
239```
240
241### Code Quality
242
243```bash
244# Format code
245cargo fmt
246
247# Lint with clippy
248cargo clippy -- -D warnings
249
250# Check for security vulnerabilities
251cargo audit
252```
253
254### Error Handling
255
256Acudo uses a structured error format for debugging:
257
258```
259error-acudo-<domain>-<number> <message>: <details>
260```
261
262Examples:
263- `error-acudo-resolve-1`: DID resolution failures
264- `error-acudo-oauth-1`: OAuth flow errors
265- `error-acudo-signature-1`: Signature verification failures
266
267## Future Directions
268
269### Planned Features
270
271- **Federated Events**: Cross-instance event discovery and aggregation
272- **Portable Tickets**: Transfer tickets between AT Protocol identities
273- **Verifiable Attendance**: Zero-knowledge proofs for privacy-preserving attendance verification
274- **Badge Marketplace**: Trade and showcase rare event badges
275- **Analytics Dashboard**: Event organizer insights with privacy preservation
276
277### Protocol Evolution
278
279Acudo is designed to evolve with the AT Protocol ecosystem:
280
2811. **Lexicon Evolution**: New record types for richer event experiences
2822. **DID Methods**: Support for emerging DID methods beyond PLC and Web
2833. **Federation**: Multi-instance event networks with shared badge recognition
2844. **Interoperability**: Bridge to other decentralized identity systems
285
286## Contributing
287
288We welcome contributions from the community! Areas of particular interest:
289
2901. **Badge Rule Templates**: Share interesting rule patterns for badge awards
2912. **OAuth Providers**: Add support for additional OAuth backends
2923. **Performance**: Optimization of hot paths and database queries
2934. **Accessibility**: Improve screen reader support and keyboard navigation
2945. **Internationalization**: Add support for multiple languages
295
296### Development Setup
297
2981. Fork the repository
2992. Set up local PostgreSQL with the test database
3003. Configure `.env` file with test credentials
3014. Run `cargo test` to verify setup
3025. Create feature branch and make changes
3036. Ensure all tests pass and code is formatted
3047. Submit pull request with clear description
305
306For detailed architecture documentation and development guidelines, see `CLAUDE.md`.
307
308## License
309
310MIT License - see LICENSE file for details.