🦋 Moods ATProto Integration - Getting Started #

Created: October 14, 2025
Status: Ready for implementation

---

📖 Quick Start #

This integration adds ATProto support to Aesthetic Computer's moods system, enabling moods to be stored on both MongoDB (primary) and ATProto PDS (federated).

What You Need to Know #

1. MongoDB stays primary - All existing moods remain, no migration risk
2. Dual-write pattern - New moods go to both MongoDB + ATProto
3. Graceful degradation - If ATProto fails, MongoDB still works
4. Backfill supported - Historical moods can be migrated
5. Delete syncs - Deleting account removes moods from both

---

📁 Files Overview #

/at/
├── MOODS-ATPROTO-INTEGRATION-PLAN.md   ⭐ Complete implementation guide
├── MOODS-INTEGRATION-SUMMARY.md         📋 Quick reference
├── MOODS-INTEGRATION-CHECKLIST.md       ✅ Track progress
├── GET-STARTED.md                       👈 You are here
├── lexicons/computer/aesthetic/
│   └── mood.json                        🦋 ATProto schema
└── scripts/
    └── moods-integration-commands.sh    🔧 Quick commands

Where to Start #

1. Planning: Read MOODS-INTEGRATION-SUMMARY.md (5 min read)
2. Deep Dive: Read MOODS-ATPROTO-INTEGRATION-PLAN.md (30 min)
3. Tracking: Use MOODS-INTEGRATION-CHECKLIST.md during implementation

---

🎯 Implementation Path #

Step 1: Review Current System #

# Check existing moods in MongoDB
node scripts/audit-mood-atproto-sync.mjs 10

# See current mood endpoint
curl https://aesthetic.computer/api/mood/all | jq '.moods[:3]'

Step 2: Deploy Lexicon #

# Create deployment script (Phase 1)
# See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Phase 1
node scripts/create-mood-lexicon.mjs --deploy

Step 3: Implement Backend #

# Create helper (Phase 2.1)
# File: /system/backend/mood-atproto.mjs
# See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Phase 2.1

# Update mood function (Phase 2.2)
# File: /system/netlify/functions/mood.mjs
# See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Phase 2.2

Step 4: Test Integration #

# Create test mood
curl -X POST http://localhost:8888/api/mood \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"mood": "testing atproto!"}'

# Verify in MongoDB
node scripts/audit-mood-atproto-sync.mjs @testuser

# Check ATProto PDS
# (Commands in plan document)

Step 5: Backfill Historical #

# Dry run
node scripts/migrate-moods-to-atproto.mjs

# Execute
node scripts/migrate-moods-to-atproto.mjs --execute

Step 6: Enable Deletion Sync #

# Update delete function (Phase 3)
# File: /system/netlify/functions/delete-erase-and-forget-me.mjs
# See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Phase 3

---

🧪 Testing Strategy #

Manual Testing #

# 1. Create mood with ATProto user
curl -X POST https://aesthetic.computer/api/mood \
  -H "Authorization: Bearer TOKEN" \
  -d '{"mood": "happy!"}'

# 2. Check MongoDB has atproto.uri
mongosh --eval 'db.moods.findOne({user: "auth0|123..."})'

# 3. Verify on PDS
node scripts/audit-mood-atproto-sync.mjs @handle

Automated Testing #

See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Phase 5 - Testing Checklist

---

📊 Schema Changes #

MongoDB Moods Collection #

Before:

{
  _id: ObjectId("abc123"),
  user: "auth0|123...",
  mood: "feeling good",
  when: ISODate("2025-10-14"),
  deleted: false
}

After:

{
  _id: ObjectId("abc123"),
  user: "auth0|123...",
  mood: "feeling good",
  when: ISODate("2025-10-14"),
  deleted: false,
  atproto: {                    // ← NEW
    uri: "at://did:plc:abc.../computer.aesthetic.mood/3k...",
    cid: "bafyrei...",
    created: ISODate("2025-10-14"),
    synced: true
  }
}

ATProto Record #

{
  $type: "computer.aesthetic.mood",
  text: "feeling good",
  createdAt: "2025-10-14T12:00:00Z",
  isPrivate: false,
  mongoId: "abc123"  // Back-reference
}

---

🔧 Key Scripts to Create #

During implementation, you'll create these scripts:

Phase 1: Lexicon #

• scripts/create-mood-lexicon.mjs - Deploy lexicon to PDS

Phase 2: Backend #

• system/backend/mood-atproto.mjs - Helper functions

Phase 4: Migration #

• scripts/migrate-moods-to-atproto.mjs - Backfill historical moods

Phase 5: Auditing #

• scripts/audit-mood-atproto-sync.mjs - Verify sync status

See full code samples in MOODS-ATPROTO-INTEGRATION-PLAN.md

---

🚨 Important Considerations #

What Works Without ATProto #

✅ Creating moods (MongoDB only)
✅ Reading moods
✅ Deleting moods
✅ All existing functionality

What Requires ATProto #

🦋 Federating moods to ATProto network
🦋 Cross-PDS mood discovery
🦋 ATProto-native mood apps

Rollback Safety #

• MongoDB is primary, ATProto is secondary
• Can disable ATProto sync anytime without breaking moods
• Can remove atproto field from MongoDB if needed
• ATProto records can be deleted separately

---

📞 Need Help? #

Documentation #

• Full plan: MOODS-ATPROTO-INTEGRATION-PLAN.md
• Quick ref: MOODS-INTEGRATION-SUMMARY.md
• Checklist: MOODS-INTEGRATION-CHECKLIST.md

Commands #

# Show all quick commands
./scripts/moods-integration-commands.sh

Common Issues #

See MOODS-ATPROTO-INTEGRATION-PLAN.md Section: Edge Cases & Considerations

---

✅ Definition of Done #

Project is complete when:

• ✅ Lexicon deployed to PDS
• ✅ New moods auto-create ATProto records
• ✅ Historical moods backfilled
• ✅ Delete syncs to both MongoDB + ATProto
• ✅ Audit shows 100% sync rate
• ✅ Tests passing
• ✅ Documentation complete
• ✅ Monitoring in place

---

🚀 Ready to Start? #

1. Read MOODS-INTEGRATION-SUMMARY.md (5 min)
2. Open MOODS-INTEGRATION-CHECKLIST.md to track progress
3. Follow MOODS-ATPROTO-INTEGRATION-PLAN.md step-by-step
4. Use scripts/moods-integration-commands.sh for quick reference

Estimated Time: 3-4 weeks
Complexity: Medium
Risk: Low (MongoDB stays primary)

---

Let's build it! 🦋