managarten/docs/README_ENV_AUDIT.md

Environment Configuration Audit - Complete Documentation

This folder contains a comprehensive audit of all backend environment variable configurations in the Mana Universe monorepo.

Documents

1. ENV_CONFIGURATION_AUDIT.md - MAIN REPORT

The complete audit with all findings and detailed analysis

• Section 1: Port Assignment Matrix (identifies 2 port conflicts)
• Section 2: Auth Environment Variables (missing variables, inconsistent naming)
• Section 3: Environment Variable Mapping Audit (coverage analysis)
• Section 4: Hardcoded Values & Security Concerns (DEV_USER_ID, CORS)
• Section 5: Configuration Best Practices Compliance (validation schemas)
• Section 6: Critical Issues Summary (8 issues identified)
• Section 7: Recommended Actions (3 implementation phases)
• Section 8: Updated Port Assignments (proposed fixes)
• Section 9: Environment Variable Summary Tables
• Section 10: Implementation Checklist (16 action items)

Read this if: You need the complete, detailed analysis with code examples and full context.

Lines: 408 | Size: 14KB

---

2. ENV_AUDIT_SUMMARY.md - QUICK START GUIDE

Executive summary with actionable checklists and next steps

• Quick Issue Overview: Blocking, Major, and Medium issues at a glance
• Phase-Based Checklist: Quick fix checklist organized by priority
• Port Mapping: Visual comparison of current vs. recommended ports
• Environment Variable Status: What's working and what needs work
• Files to Modify: Concrete list of files that need changes
• Testing Instructions: How to verify fixes
• Additional Resources: Links to full documentation

Read this if: You need a quick overview and want to start fixing issues immediately.

Lines: 166 | Size: 5KB

---

3. ENV_BACKEND_MATRIX.md - DETAILED MATRIX VISUALIZATION

Backend configuration status visualized in detailed tables and matrices

• Backend Status Matrix: Port, Auth URL, Dev Bypass, Validation status
• Database Configuration: Which backends have database URLs
• CORS Configuration: How CORS is implemented (hardcoded vs. environment)
• Port Availability & Conflicts: Visual representation of port assignments
• Environment Variable Generation Map: How variables flow from .env.development
• Severity Matrix: Issue counts and time estimates
• Best Practices Scorecard: Overall quality assessment (5.1/10)
• Variable Standardization Guide: Current inconsistencies and path to consistency

Read this if: You want to understand the full scope of backend configurations visually.

Lines: 234 | Size: 8KB

---

Key Findings Summary

BLOCKING ISSUES (Fix Immediately)

1. Port 3002 Conflict: Chat and Nutriphi both use port 3002
2. Port 3003 Conflict: Picture and Maerchenzauber both use port 3003
3. Hardcoded DEV_USER_ID: Chat backend hardcodes 17cb0be7-058a-4964-9e18-1fe7055fd014

MAJOR ISSUES (Fix Soon)

4. Auth URL Naming Inconsistency:

   • Manadeck uses MANA_SERVICE_URL (should be MANA_CORE_AUTH_URL)
   • Nutriphi uses MANACORE_AUTH_URL (should be MANA_CORE_AUTH_URL)
   • Chat, Picture, Zitare, Presi use correct MANA_CORE_AUTH_URL

5. Hardcoded CORS Origins: 4 backends hardcode allowed origins instead of using environment variable

6. Missing Configuration Examples:

   • No .env.example for Zitare backend
   • No .env.example for Presi backend

MEDIUM ISSUES (Improve Quality)

7. Missing Validation Schemas: Chat, Picture, Zitare, Presi lack Joi validation schemas

8. Inconsistent Dev Bypass Auth: Only Chat backend implements DEV_BYPASS_AUTH

---

Quick Fix Timeline

Phase	Tasks	Time	Impact
Phase 1	Fix ports + add DEV_USER_ID	15-30 min	CRITICAL - Enables simultaneous backend execution
Phase 2	Standardize naming + add .env examples	30 min	MAJOR - Improves consistency
Phase 3	Add validation schemas + extract CORS	2-3 hours	QUALITY - Code quality improvement

Total estimated time to fix all issues: 6-8 hours

---

Which Document Should I Read?

I want to...

...quickly understand what's wrong → Read ENV_AUDIT_SUMMARY.md (5 min read)

...get detailed analysis with code examples → Read ENV_CONFIGURATION_AUDIT.md (20 min read)

...see all backend configurations visually → Read ENV_BACKEND_MATRIX.md (10 min read)

...start fixing issues immediately → Read ENV_AUDIT_SUMMARY.md "Quick Fix Checklist" section

...understand the complete scope → Read all three documents in order (1 → 2 → 3)

---

Implementation Roadmap

If you have 30 minutes

1. Read ENV_AUDIT_SUMMARY.md
2. Fix port conflicts in .env.development
3. Add DEV_USER_ID variable

If you have 1-2 hours

1. Complete Phase 1 fixes
2. Update generate-env.mjs variable names
3. Create .env.example files for Zitare and Presi

If you have 4+ hours

1. Complete all Phase 1 & 2 fixes
2. Add validation schemas to all backends
3. Extract CORS origins to environment variables
4. Test all backends can run simultaneously

---

Files Analyzed in This Audit

Configuration Files:

• .env.development (202 lines)
• scripts/generate-env.mjs (433 lines)
• services/mana-core-auth/.env.example
• apps/chat/apps/backend/.env.example
• apps/picture/apps/backend/.env.example
• apps/manadeck/apps/backend/.env.example

Backend Configuration:

• 6 app.module.ts files (NestJS configuration)
• 5 main.ts files (server bootstrap & CORS)
• 1 validation.schema.ts file (Manadeck)
• Multiple JWT auth guard files

Total Files Analyzed: 25+ Total Lines Reviewed: 2,000+ Issues Identified: 8 critical/major items, 17 total issues

---

Recommendations by Priority

Priority 1: BLOCKING (Do Today)

• Fix PICTURE_BACKEND_PORT: 3003 → 3005
• Fix NUTRIPHI_BACKEND_PORT: 3002 → 3006
• Add DEV_USER_ID to .env.development
• Update Chat backend to read DEV_USER_ID from ConfigService

Priority 2: MAJOR (Do This Week)

• Rename MANA_SERVICE_URL to MANA_CORE_AUTH_URL in Manadeck
• Rename MANACORE_AUTH_URL to MANA_CORE_AUTH_URL in Nutriphi
• Create .env.example for Zitare backend
• Create .env.example for Presi backend

Priority 3: MEDIUM (Plan This Week)

• Add validation schemas to 4 backends (Chat, Picture, Zitare, Presi)
• Extract CORS origins to CORS_ORIGINS environment variable
• Update all backends to use env variable for CORS
• Document final port assignments in project CLAUDE.md files

Priority 4: LONG-TERM (Future Improvement)

• Implement consistent dev bypass auth pattern across all backends
• Add comprehensive integration tests for all backends
• Document environment configuration in deployment guide
• Set up CI/CD to validate .env configuration changes

---

Success Criteria

After implementing all recommendations, you should be able to:

1. Run all 8 active backends simultaneously without port conflicts

   pnpm dev:auth &
   pnpm dev:chat:backend &
   pnpm dev:picture:backend &
   pnpm dev:manadeck:backend &
   pnpm dev:zitare:backend &
   pnpm dev:presi:backend &
   

2. Every backend loads from .env without warnings

   • All required variables present
   • All variables properly typed/validated

3. Consistent naming conventions across all backends

   • Same auth URL variable name used everywhere
   • Same database URL pattern
   • Same CORS configuration approach

4. All backends properly documented

   • Each has .env.example file
   • Each has configuration validation schema
   • Port assignments documented in CLAUDE.md

5. Security best practices enforced

   • No hardcoded values in source code
   • All secrets loaded from environment
   • Configuration validated on startup

---

Contact & Questions

If you have questions about any findings:

1. Detailed findings → See ENV_CONFIGURATION_AUDIT.md section numbers
2. Implementation guidance → See ENV_AUDIT_SUMMARY.md "Files to Modify"
3. Visual reference → See ENV_BACKEND_MATRIX.md tables

---

Document Metadata

Audit Date: December 1, 2025 Auditor: Environment Configuration Auditor Agent Swarm Role: Claude Flow Swarm - Configuration Validation Team Monorepo Version: manacore-monorepo (main branch) Total Issues: 8 critical/major + 9 medium/quality issues

Status: READY FOR IMPLEMENTATION

---

Next Action: Read ENV_AUDIT_SUMMARY.md and start with Phase 1 fixes.