🏗️ Architecture: How should we resolve parallel role vocabularies (VittoUserT...

Date: 2026-03-19
Time: 21:04:26 UTC
Session: gspace1-242.2
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How should we resolve parallel role vocabularies (VittoUserType, VittoLayer, JWT roles vs PlatformRole) without breaking Mongo documents or active Vitto/chat flows?

Task: S242 MCP knowledge capture after role-system cleanup handoff

🎯 Decision Made

Chosen:

Single source of truth: role-derivation.ts (PlatformRole + derivePermissions). Map legacy JWT roles at boundaries (platformRoleFromLegacyRoles); persist platformRole on User; replace Vitto UI tiers with PlatformRole-derived features; rename VittoLayer to VittoConfigAccess for task config; extend Mongo enums (executive, userType) rather than destructive migration.

Options Considered:

1. Full breaking rename of all stored role fields
2. Status quo with ad-hoc string checks per service

💭 Reasoning

Root cause: S220 introduced PlatformRole but adoption was partial, causing manager→admin inflation, dead space_builder JWT branch, wrong builder context strings, and schema drift. Alternatives of full DB-only PlatformRole or deleting vitto-chat.service without consumers were rejected per handoff (keep RegistrationUserType / hierarchy enums). Prevention: grep for new parallel role types; document Mongo backfills in runbook; align schema comments to L0–L4.

📁 Files Involved

• libs/libs-foundational/core-models/src/lib/utils/role-derivation.ts
• APIs/backend-api/src/app/backend-auth/backend-auth.service.ts
• APIs/backend-ai-api/src/app/chat/chat.controller.ts
• APIs/backend-vitto-api/src/app/types/vitto.types.ts
• libs/libs-ai/vitto-chat/src/lib/types/chat.types.ts
• libs/libs-ai/gograb-ai-lib/src/lib/components/vitto-hub/vitto-hub.component.ts
• docs/superpowers/plans/2026-03-19-role-system-mongodb-runbook.md

🔗 Related

• Decision ID: dev_1773954266624_5l9yrbh
• Session: 242
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation