Open
Conversation
Single source of truth for workflow generation conventions: architecture layers, node naming, payload schema, error handling, stack, tagging, and production checklist. https://claude.ai/code/session_01M47pNyJ3JEP7zf34SsVcbW
Adds the complete foundation for the Luxee multi-channel inbox application: ## luxee-inbox/ (new Next.js 15 app) - package.json with Next.js 15, Supabase SSR, Anthropic SDK, Radix UI, Tailwind - Supabase migration 001: full inbox schema (conversations, messages, drafts, ai_suggestions, qualifications, channel_connections, contacts, tags, events_log) with RLS, Realtime, indexes, and triggers - TypeScript types generated from schema - App Router structure: (auth)/login, (inbox)/inbox/[id] - Supabase client/server helpers - Webhook routes: POST /api/webhooks/twilio, POST /api/webhooks/outlook - API route: POST /api/conversations/[id]/send - Core UI: ConversationList (realtime), ConversationThread (realtime), ReplyComposer, Sidebar, ChannelBadge, PriorityDot - Luxee design tokens: dark premium, violet accent, channel color system ## CONVENTIONS.md (extended) - Section 13: Multi-channel canonical message payload - Channel mappings: Twilio SMS, WhatsApp, Outlook, LinkedIn - Bridge Code node reference for Twilio SMS - AI group update spec ## workflows/specs/ - Full spec for [Luxee] Inbox — Inbound SMS Handler (P0 workflow) with all 10 layers, node-by-node spec, test payload, dependencies, and production checklist per CONVENTIONS.md https://claude.ai/code/session_01M47pNyJ3JEP7zf34SsVcbW
Production-ready n8n workflow (18 nodes, CONVENTIONS.md-compliant) for receiving inbound Twilio SMS, normalizing to canonical payload, persisting to Supabase, and triggering async AI analysis. Architecture layers implemented: - TRIGGER: Webhook (responseMode: onReceived — responds 200 immediately) - BRIDGE: Normalize Twilio body → canonical message payload (§13 spec) - VALIDATION: IF node — MessageSid, Body, From (E.164 regex) in AND - IDEMPOTENCY: Code node httpRequest — deduplicates by external_message_id - PROCESSING: Resolve channel_connection, find-or-create contact/conversation - OUTPUT: Insert message row, PATCH conversation, fire-and-forget AI webhook - LOGGING: Write events_log on success, on duplicate skip, on error - ERROR: Classify error (validation_failed vs channel_not_configured) - NOTIFICATION: Slack alert — fatal errors only (should_alert flag) All Code nodes use this.helpers.httpRequest() + $env.SUPABASE_URL / $env.SUPABASE_SERVICE_KEY. No Function nodes. No Wait nodes. No HTTP Request nodes in non-terminal positions. Data flows forward through spread operator pattern (...data, _newField: ...). Required env vars: SUPABASE_URL, SUPABASE_SERVICE_KEY, N8N_WEBHOOK_AI_ANALYZER, SLACK_WEBHOOK_OPS https://claude.ai/code/session_01M47pNyJ3JEP7zf34SsVcbW
=== Workflow: Inbound SMS Handler (v1.0 → v1.1) ===
Payload compliance (§3.3 + §13.2):
- BRIDGE rewritten: adds execution_timestamp, source_event, entity_id,
client_id, domain, status (were all missing in v1.0)
- contact group: adds name, email, company, external_identifier
- channel group: provider/account_sid/geo moved to channel.metadata
- ai group: renamed to match §13.2 (priority, score, next_action, labels,
suggestion, qualification{}, processed_at — were misnamed)
- routing group: path, priority, requires_human_review, assigned_to (§13.2)
- trace_id: uses crypto.randomUUID() fallback (was null on missing MessageSid)
Bug fix:
- IDEMPOTENCY: was checking data.trace_id, now correctly uses
data.message.external_message_id
Error architecture (§19 two-level model):
- Add [ROUTER] Tag Validation Error — injects _error_source before ERROR Classify
- Add [ROUTER] Tag Channel Error — injects _error_source before ERROR Classify
- [ERROR] Classify Error: now reads _error_source via errorDefinitions map,
never infers from payload state
Race condition hardening (§18):
- Resolve or Create Contact: UPSERT via on_conflict=phone +
resolution=ignore-duplicates + re-fetch fallback (handles concurrent inbound)
- Resolve or Create Conversation: GET → POST → re-fetch fallback pattern
Reliability:
- [OUTPUT] Insert Message: try/catch with enriched rethrow for global Error Trigger
- [OUTPUT] Update Conversation: simplified to only set last_workflow_trace_id
(DB trigger handles last_message_at + is_read automatically)
- [OUTPUT] Trigger AI: failure now always logged to events_log (warning)
before continuing — never silently swallowed
- [LOGGING] Write Execution Log: includes ai_trigger_status in payload
=== CONVENTIONS.md ===
§8 Code node rules: strengthened with explicit justified/prohibited patterns
§12 Checklist: expanded with payload, error model, webhook, and logging checks
§13.4 BRIDGE reference: updated to v1.1 (all required fields, metadata placement)
§15 NEW: Webhook response policy (responseMode, provider timeout, retry risk)
§16 NEW: Code node discipline (native-first table, justified uses, prohibited patterns)
§17 NEW: Async non-blocking action failure policy (mandatory logging pattern)
§18 NEW: Resolve-or-create pattern and race condition policy (UPSERT + fallback)
§19 NEW: Error architecture two-level model (business vs technical, routing rules)
§20 Final rule (renumbered from §14)
https://claude.ai/code/session_01M47pNyJ3JEP7zf34SsVcbW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.