A Minecraft Fabric mod that connects the game with ATProtocol ⛏️
1# Social Sync Documentation Index
2
3Welcome to the Social Sync documentation. This index helps you find the information you need.
4
5## Getting Started
6
7- **First Time?** Start with [README.md](../README.md)
8- **Want to install?** See [Installation](../README.md#installation)
9- **Want to set up AppView?** See [AppView Quick Start](APPVIEW_QUICKSTART.md)
10
11## Documentation Structure
12
13### For Users
14
15| Document | Purpose | Audience |
16|----------|---------|----------|
17| [README.md](../README.md) | Project overview & features | Everyone |
18| [APPVIEW_QUICKSTART.md](APPVIEW_QUICKSTART.md) | Deploy AppView service | Server Operators |
19| [TEST_GUIDE.md](TEST_GUIDE.md) | Run and write tests | Developers |
20
21### For Developers
22
23| Document | Purpose | Audience |
24|----------|---------|----------|
25| [API_REFERENCE.md](API_REFERENCE.md) | Complete API documentation | API Developers |
26| [ARCHITECTURE.md](ARCHITECTURE.md) | System design & internals | Core Developers |
27| [TEST_GUIDE.md](TEST_GUIDE.md) | Testing framework & practices | QA Engineers |
28
29### For System Administrators
30
31| Document | Purpose | Audience |
32|----------|---------|----------|
33| [ARCHITECTURE.md](ARCHITECTURE.md#deployment-scenarios) | Deployment options | DevOps/Admins |
34| [APPVIEW_QUICKSTART.md](APPVIEW_QUICKSTART.md) | AppView deployment | DevOps/Admins |
35| [ARCHITECTURE.md](ARCHITECTURE.md#monitoring--operations) | Monitoring & operations | Operators |
36
37### For Community
38
39| Document | Purpose | Audience |
40|----------|---------|----------|
41| [APPVIEW.md](APPVIEW.md) | How AppView works | Community Members |
42| [APPVIEW.md](APPVIEW.md#integration-with-at-protocol-clients) | Bluesky integration | Integrators |
43
44## Quick Links by Topic
45
46### Authentication & Security
47- [Authentication Overview](../README.md#authentication--security)
48- [API Authentication Methods](API_REFERENCE.md#authentication--session-management)
49- [Security Best Practices](../README.md#security-best-practices)
50
51### Commands
52- [Command List](../README.md#available-commands)
53- [Command Examples](../README.md#example-workflow)
54- [Command System Architecture](ARCHITECTURE.md#1-command-system)
55
56### Data Syncing
57- [Data Syncing Overview](../README.md#data-syncing)
58- [Sync Services Architecture](ARCHITECTURE.md#4-data-syncing-services)
59- [Record Management API](API_REFERENCE.md#record-management)
60
61### AppView
62- [AppView Overview](APPVIEW.md#overview)
63- [AppView API](APPVIEW.md#api-endpoints)
64- [AppView Setup](APPVIEW_QUICKSTART.md#setup-steps)
65- [AppView Architecture](ARCHITECTURE.md#33-record-management)
66
67### Testing
68- [Test Guide](TEST_GUIDE.md)
69- [Running Tests](TEST_GUIDE.md#running-tests)
70- [Writing Tests](TEST_GUIDE.md#writing-new-tests)
71
72### Deployment
73- [Installation](../README.md#installation)
74- [Configuration](../README.md#configuration-files)
75- [Deployment Guide](ARCHITECTURE.md#deployment-scenarios)
76- [Server Setup](APPVIEW_QUICKSTART.md#setup-steps)
77
78### Troubleshooting
79- [Common Issues](ARCHITECTURE.md#troubleshooting)
80- [AppView Issues](APPVIEW.md#troubleshooting)
81- [Test Issues](TEST_GUIDE.md#troubleshooting)
82
83## API Reference by Component
84
85### Session Management
86- [AtProtoSessionManager](API_REFERENCE.md#atprotosessionmanager) - Authentication & sessions
87- [Session Data Model](API_REFERENCE.md#session-data-model) - Session structure
88
89### Record Management
90- [RecordManager](API_REFERENCE.md#recordmanager) - CRUD operations
91- [Create Operations](API_REFERENCE.md#create-operations) - Creating records
92- [Read Operations](API_REFERENCE.md#read-operations) - Retrieving records
93- [Update Operations](API_REFERENCE.md#update-operations) - Updating records
94- [Delete Operations](API_REFERENCE.md#delete-operations) - Deleting records
95
96### Security
97- [SecurityUtils](API_REFERENCE.md#securityutils) - Encryption & validation
98- [SecurityAuditor](API_REFERENCE.md#securityauditor) - Event logging
99- [RateLimiter](API_REFERENCE.md#ratelimiter) - Brute-force protection
100
101### Storage
102- [PlayerIdentityStore](API_REFERENCE.md#playeridentitystore) - UUID↔DID mapping
103- [PlayerSyncPreferencesStore](API_REFERENCE.md#playersyncpreferencesstore) - Sync settings
104- [Configuration Files](API_REFERENCE.md#configuration-files) - File storage
105
106### AppView
107- [AppViewService](APPVIEW.md#appviewservice) - Indexing & querying
108- [AppViewHttpServer](APPVIEW.md#appviewhttpserver) - HTTP API
109- [Query Endpoints](APPVIEW.md#query-operations) - Available queries
110
111## Code Examples
112
113### Quick Examples
114- [AppView Examples](examples/AppViewExample.kt) - 10 working scenarios
115- [Record Creation](examples/RecordCreationExample.kt) - Creating records
116- [Record Manager](examples/RecordManagerExamples.kt) - CRUD operations
117
118### Advanced Topics
119- [End-to-End Workflow](ARCHITECTURE.md#example-2-stats-syncing-flow) - Complete data flow
120- [Custom AppView](APPVIEW_QUICKSTART.md#integration-examples) - Building integrations
121- [Performance Optimization](ARCHITECTURE.md#performance-optimization) - Tuning
122
123## Glossary
124
125| Term | Definition |
126|------|-----------|
127| **AT Protocol** | Decentralized social protocol powering Bluesky |
128| **DID** | Decentralized Identifier (user identity on AT Protocol) |
129| **Handle** | Human-readable username (e.g., alice.bsky.social) |
130| **PDS** | Personal Data Server (stores user's data) |
131| **AppView** | Service that displays/queries published records |
132| **Lexicon** | Schema definitions for records |
133| **XRPC** | AT Protocol's RPC mechanism |
134| **TID** | Timestamp-based ID for records |
135| **rkey** | Record key (TID or "self" for literal records) |
136
137## File Structure
138
139```
140docs/
141├── README.md # This index
142├── API_REFERENCE.md # Complete API documentation (500+ lines)
143├── ARCHITECTURE.md # System design & deployment (600+ lines)
144├── APPVIEW.md # AppView guide (600+ lines)
145├── APPVIEW_QUICKSTART.md # AppView setup (400+ lines)
146├── APPVIEW_INDEX.md # AppView documentation index
147├── APPVIEW_COMPLETION.md # Feature completion summary
148├── TEST_GUIDE.md # Testing documentation (300+ lines)
149└── examples/
150 ├── AppViewExample.kt # 10 working examples
151 ├── RecordCreationExample.kt
152 └── RecordManagerExamples.kt
153
154src/
155├── main/
156│ ├── kotlin/com/jollywhoppers/
157│ │ ├── socialsync.kt # Main initializer
158│ │ └── atproto/
159│ │ ├── server/
160│ │ │ ├── AppViewService.kt # AppView indexing
161│ │ │ ├── AppViewHttpServer.kt # AppView HTTP API
162│ │ │ ├── RecordManager.kt # Record CRUD
163│ │ │ ├── At*.kt # Core services
164│ │ │ └── *SyncService.kt # Sync services
165│ │ ├── security/
166│ │ │ ├── SecurityUtils.kt
167│ │ │ ├── RateLimiter.kt
168│ │ │ └── SecurityAuditor.kt
169│ │ └── client/
170│ │ └── *
171│ └── resources/
172│ ├── lexicons/ # Lexicon schemas
173│ └── assets/
174└── test/
175 └── kotlin/com/jollywhoppers/
176 ├── CoreTests.kt # Main test suite (20+ tests)
177 └── ...
178```
179
180## Documentation Statistics
181
182| Metric | Value |
183|--------|-------|
184| Total Documentation | 3,500+ lines |
185| API Reference | 500+ lines |
186| Architecture Guide | 600+ lines |
187| Test Guide | 300+ lines |
188| Code Examples | 10 complete scenarios |
189| Test Coverage | 20+ tests |
190
191## Contributing to Documentation
192
193If you're adding a new feature:
194
1951. **Add API Documentation** - Document new methods in API_REFERENCE.md
1962. **Add Examples** - Create example code in docs/examples/
1973. **Add Tests** - Add test cases in src/test/
1984. **Update Architecture** - Update ARCHITECTURE.md if it changes system design
1995. **Add to Index** - Link from this index
200
201## Maintenance Schedule
202
203| Task | Frequency |
204|------|-----------|
205| Update examples | Monthly |
206| Review API docs | Quarterly |
207| Update architecture | As needed |
208| Audit test coverage | Monthly |
209
210## Support
211
212**Questions?**
213- Check the index above
214- Search in relevant documentation
215- Check code examples
216- Review troubleshooting sections
217
218**Found an issue?**
219- Report in Issues
220- Include documentation link
221- Suggest improvements
222
223**Want to contribute?**
224- Follow contribution guidelines
225- Submit pull request with docs
226- Link to this index from new docs
227
228## Additional Resources
229
230### External Links
231- [AT Protocol Documentation](https://atproto.com/)
232- [Bluesky Documentation](https://docs.bsky.app/)
233- [Lexicon Specification](https://atproto.com/specs/lexicon)
234- [XRPC Reference](https://atproto.com/specs/xrpc)
235
236### Related Docs
237- [Project README](../README.md)
238- [License](../LICENSE)
239- [Contributing Guide](../README.md#contributing)
240
241---
242
243**Last Updated**: April 2026
244**Version**: 0.5.0
245**Status**: Complete ✅
246
247## Quick Navigation
248
249- [🏠 Home](../README.md)
250- [📚 Full Docs](../docs/)
251- [🔧 API Reference](API_REFERENCE.md)
252- [🏗️ Architecture](ARCHITECTURE.md)
253- [🧪 Tests](TEST_GUIDE.md)
254- [👀 AppView](APPVIEW.md)
255- [💾 Examples](examples/)