🏗️ Architecture: Session 124: How does the space invitation system work end-t...

Date: 2026-02-19
Time: 21:36:38 UTC
Session: gspace1-125.128
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

Session 124: How does the space invitation system work end-to-end?

Task: Not specified

🎯 Decision Made

Chosen:

SpaceInvitation MongoDB schema (space_invitations collection) with 32-byte crypto tokens + 6-digit short codes. Flow: Admin creates invite via POST /api/invitations (selects space, role, phone, channel) -> Backend generates tokens, stores in DB, sends SMS/WhatsApp via TwilioService from @libs-api/messaging-core -> Recipient gets 6-digit code + full URL link -> Opens /join/:token or enters code at /auth/register -> Frontend auto-validates via GET /api/invitations/:code/validate (debounced 600ms) -> Shows space name + assigned role -> User fills registration form -> POST /auth/register with inviteCode -> Backend validates invite, creates user with role FROM invite (not user choice), adds to space.members, marks invite accepted -> Returns JWT with spaceId.

Options Considered:

• No alternatives documented

💭 Reasoning

Modeled after Slack/Notion invite pattern. Role determined by inviter not joiner (security). 6-digit codes are SMS-friendly. Full tokens for URL links (256-bit entropy). Rate limited: 5 validate attempts/min/IP, 10 failed attempts locks the invite. 7-day expiry default. TTL index auto-cleans. Reused existing TwilioService (sendSms + sendWhatsAppMessage). Admin chooses delivery channel (SMS, WhatsApp, or manual).

📁 Files Involved

• apis/backend-api/src/app/spaces/space-invitation.schema.ts
• apis/backend-api/src/app/spaces/space-invitation.service.ts
• apis/backend-api/src/app/spaces/space-invitation.controller.ts
• apis/backend-api/src/app/backend-auth/backend-auth.service.ts

🔗 Related

• Decision ID: dev_1771536998465_w7ipzxc
• Session: 125
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation