🏗️ Architecture: How should generated module path aliases be structured to pr...

Date: 2026-03-10
Time: 21:12:17 UTC
Session: gspace1-200.4
Agent: architecture
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should generated module path aliases be structured to prevent collisions and match the directory layout?

Task: S200: Module path alias architecture

🎯 Decision Made

Chosen:

Category-aware aliases: @module/{category}/{slug} mapping to modules/{category}/{slug}/src. Category flows from normalizeDecomposeResult through file generation, path registration, app shell imports, and package.json naming.

Options Considered:

1. @module/{slug} with category only in directory path
2. @module/{category}/{slug} everywhere (chosen)
3. @module/{category}-{slug} flat naming

💭 Reasoning

The original @module/{slug} pattern caused two problems: (1) No disambiguation if two modules in different categories had the same slug, (2) The alias didn't reflect the actual directory structure (modules/{category}/{slug}/), making it impossible to determine the physical location from the alias alone. The category is a first-class architectural concept that must be consistent across all touchpoints: tsconfig paths, package.json name, app shell lazy imports, and GitLab repo file paths. The inferModuleCategory() function in module-generation.types.ts provides smart defaults from module names (dashboard→layout, auth→auth, analytics→analytics) preventing the 'structural' soup problem.

📁 Files Involved

• APIs/backend-vitto-api/src/app/module-generation/phases/module-gen-phase.executor.ts
• APIs/backend-vitto-api/src/app/module-generation/generators/app-shell-generator.service.ts
• APIs/backend-vitto-api/src/app/module-generation/module-generation.types.ts
• config/tsconfig-paths/modules/generated.paths.json

🔗 Related

• Decision ID: dev_1773177136998_fjlc8t2
• Session: 200
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation