mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:21:09 +02:00
ad495b2044
Optimize CLAUDE.md based on industry best practices from HN and HumanLayer:
Changes:
- Trim CLAUDE.md from 678 to 176 lines (74% reduction, 5.7KB)
- Add "Critical Gotchas" section for common AI mistakes
- Add verification signature (🏗️ ManaCore Monorepo)
- Create docs/README.md navigation hub with "I want to..." index
- Delete 5 outdated audit files (ENV_AUDIT_*, DEPENDENCY_ALIGNMENT)
- Archive 7 analysis/historical docs to docs/archive/
- Keep authentication docs separate per request (.claude/guidelines/)
Benefits:
- Better AI instruction adherence (within ~150-200 line budget)
- Progressive disclosure via signposting to detailed docs
- Cleaner navigation with topic-based organization
- Reduced maintenance burden (stale docs archived)
Backup: CLAUDE.md.backup preserves original 678-line version
Change log: docs/archive/RESTRUCTURE_2025-12-16.md
264 lines
8.8 KiB
Markdown
264 lines
8.8 KiB
Markdown
# 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](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](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](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](ENV_AUDIT_SUMMARY.md) (5 min read)
|
|
|
|
**...get detailed analysis with code examples**
|
|
→ Read [ENV_CONFIGURATION_AUDIT.md](ENV_CONFIGURATION_AUDIT.md) (20 min read)
|
|
|
|
**...see all backend configurations visually**
|
|
→ Read [ENV_BACKEND_MATRIX.md](ENV_BACKEND_MATRIX.md) (10 min read)
|
|
|
|
**...start fixing issues immediately**
|
|
→ Read [ENV_AUDIT_SUMMARY.md](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**
|
|
|
|
```bash
|
|
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.
|