mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-14 20:41:09 +02:00
chore: remove stale docs and outdated design plans
- docs/AUTOMATED_TESTING_SYSTEM.md (implementation report, workflow already exists) - docs/README_ENV_AUDIT.md (index for already-deleted audit files) - docs/DEPENDENCY_ALIGNMENT.md (version tracking, immediately outdated) - .claude/plans/mana-search-service.md (draft from Jan 2025, service already built) - .claude/plans/questions-app.md (draft from Jan 2025, app already built) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Till JS
parent
fae139e7e0
commit
07365c31b2
5 changed files with 0 additions and 4095 deletions
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
|
@ -1,583 +0,0 @@
|
|||
# Automated Testing System - Implementation Summary
|
||||
|
||||
Complete automated daily test execution system with monitoring and reporting for the ManaCore monorepo.
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides an overview of the automated testing infrastructure implemented for continuous quality assurance.
|
||||
|
||||
**Implementation Date**: 2025-12-25
|
||||
**Status**: Ready for deployment
|
||||
|
||||
## Components Delivered
|
||||
|
||||
### 1. GitHub Actions Workflow
|
||||
|
||||
**File**: `.github/workflows/daily-tests.yml`
|
||||
|
||||
**Features**:
|
||||
- Scheduled daily execution at 2 AM UTC
|
||||
- Manual trigger with configurable parameters
|
||||
- Parallel test execution across multiple test suites
|
||||
- Automatic database setup/teardown per suite
|
||||
- Coverage enforcement (80% minimum)
|
||||
- Test result aggregation and reporting
|
||||
- Flaky test detection
|
||||
- Performance metrics tracking
|
||||
- Failure notifications (GitHub issues, Slack)
|
||||
|
||||
**Test Matrix**:
|
||||
- Backend tests (Jest + PostgreSQL + Redis)
|
||||
- Mobile tests (Jest + React Native)
|
||||
- Web tests (Vitest + Svelte)
|
||||
- Integration tests (E2E flows)
|
||||
|
||||
### 2. Test Execution Scripts
|
||||
|
||||
**Directory**: `/scripts/`
|
||||
|
||||
#### `/scripts/run-tests-with-coverage.sh`
|
||||
Comprehensive test execution script with coverage reporting.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Run all tests
|
||||
./scripts/run-tests-with-coverage.sh
|
||||
|
||||
# Run specific package
|
||||
./scripts/run-tests-with-coverage.sh mana-core-auth
|
||||
./scripts/run-tests-with-coverage.sh chat-backend
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- Automatic Docker verification
|
||||
- Database setup per package
|
||||
- Coverage threshold checking
|
||||
- Colored terminal output
|
||||
- Detailed summary report
|
||||
|
||||
### 3. Test Reporting Scripts
|
||||
|
||||
**Directory**: `/scripts/test-reporting/`
|
||||
|
||||
#### `aggregate-coverage.js`
|
||||
Merges coverage reports from multiple test suites.
|
||||
|
||||
**Outputs**:
|
||||
- `total-coverage.json`: Aggregated coverage data
|
||||
- `summary.md`: Markdown coverage summary
|
||||
|
||||
#### `generate-summary.js`
|
||||
Creates GitHub Actions summary with test results.
|
||||
|
||||
**Features**:
|
||||
- Coverage breakdown by suite
|
||||
- Pass/fail statistics
|
||||
- Recommendations for improvement
|
||||
|
||||
#### `detect-flaky-tests.js`
|
||||
Identifies tests that fail intermittently.
|
||||
|
||||
**Configuration**:
|
||||
- Flaky threshold: 10% failure rate
|
||||
- Minimum runs: 3
|
||||
- History retention: 30 runs per test
|
||||
|
||||
**Outputs**:
|
||||
- `flaky-tests.json`: List of flaky tests
|
||||
- `test-history.json`: Historical test data
|
||||
|
||||
#### `track-metrics.js`
|
||||
Records test performance metrics over time.
|
||||
|
||||
**Tracks**:
|
||||
- Total test execution time
|
||||
- Average test duration
|
||||
- Slowest tests
|
||||
- Suite-level metrics
|
||||
- Performance regressions (>20% increase)
|
||||
|
||||
**Outputs**:
|
||||
- `metrics.json`: Current metrics
|
||||
- `metrics-report.md`: Formatted report
|
||||
- `metrics-history.json`: 90-day history
|
||||
|
||||
#### `format-metrics.js`
|
||||
Formats metrics for GitHub Actions summary display.
|
||||
|
||||
### 4. Test Data Management
|
||||
|
||||
**Directory**: `/scripts/test-data/`
|
||||
|
||||
#### `seed-test-data.sh`
|
||||
Seeds databases with consistent test data.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Seed all services
|
||||
./scripts/test-data/seed-test-data.sh
|
||||
|
||||
# Seed specific service
|
||||
./scripts/test-data/seed-test-data.sh auth
|
||||
./scripts/test-data/seed-test-data.sh chat
|
||||
```
|
||||
|
||||
**Provides**:
|
||||
- Deterministic test user accounts
|
||||
- Pre-configured AI models (chat)
|
||||
- Consistent credit balances
|
||||
|
||||
**Test Users**:
|
||||
| Email | Password | ID | Role |
|
||||
|-------|----------|-----|------|
|
||||
| test-user-1@example.com | TestPassword123! | 00000000-0000-0000-0000-000000000001 | user |
|
||||
| test-user-2@example.com | TestPassword123! | 00000000-0000-0000-0000-000000000002 | user |
|
||||
| admin@example.com | AdminPassword123! | 00000000-0000-0000-0000-000000000003 | admin |
|
||||
|
||||
#### `cleanup-test-data.sh`
|
||||
Removes test data and resets databases.
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Clean all databases
|
||||
./scripts/test-data/cleanup-test-data.sh
|
||||
|
||||
# Clean specific database
|
||||
./scripts/test-data/cleanup-test-data.sh auth
|
||||
```
|
||||
|
||||
### 5. Documentation
|
||||
|
||||
#### `docs/TESTING_GUIDE.md`
|
||||
Comprehensive testing documentation (4000+ words).
|
||||
|
||||
**Contents**:
|
||||
- Test types and strategies
|
||||
- Local testing instructions
|
||||
- Automated daily tests overview
|
||||
- Writing tests best practices
|
||||
- Test data management
|
||||
- Coverage requirements
|
||||
- Troubleshooting guide
|
||||
- CI/CD integration
|
||||
|
||||
#### `docs/TESTING_QUICK_REFERENCE.md`
|
||||
Quick reference for common testing tasks.
|
||||
|
||||
**Contents**:
|
||||
- Quick commands
|
||||
- Test patterns and templates
|
||||
- Coverage viewing
|
||||
- Test data reference
|
||||
- Troubleshooting shortcuts
|
||||
- Best practices summary
|
||||
|
||||
#### `scripts/test-reporting/README.md`
|
||||
Documentation for test reporting scripts.
|
||||
|
||||
**Contents**:
|
||||
- Script overview and usage
|
||||
- Data format specifications
|
||||
- Development guide
|
||||
- Integration examples
|
||||
- Troubleshooting
|
||||
|
||||
### 6. Package.json Updates
|
||||
|
||||
**File**: `/package.json`
|
||||
|
||||
Added convenience scripts:
|
||||
```json
|
||||
{
|
||||
"test:cov": "./scripts/run-tests-with-coverage.sh",
|
||||
"test:seed": "./scripts/test-data/seed-test-data.sh",
|
||||
"test:cleanup": "./scripts/test-data/cleanup-test-data.sh"
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Workflow Execution Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Daily Tests Workflow (2 AM UTC) │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 1. Setup Job │
|
||||
│ - Detect test suites │
|
||||
│ - Generate test matrices │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┴─────────────┬──────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────────┐ ┌──────────┐
|
||||
│ Backend │ │ Mobile │ │ Web │
|
||||
│ Tests │ │ Tests │ │ Tests │
|
||||
│(Parallel)│ │ (Parallel) │ │(Parallel)│
|
||||
└──────────┘ └──────────────┘ └──────────┘
|
||||
│ │ │
|
||||
└─────────────┬─────────────┴──────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Integration Tests │
|
||||
│ - Full E2E flows │
|
||||
│ - Auth + Database │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┴─────────────┬──────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────────┐ ┌──────────┐
|
||||
│ Report │ │ Detect Flaky │ │ Metrics │
|
||||
│ Job │ │ Tests │ │ Tracking │
|
||||
└──────────┘ └──────────────┘ └──────────┘
|
||||
│ │ │
|
||||
└─────────────┬─────────────┴──────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Notify Job (on failure) │
|
||||
│ - GitHub issue │
|
||||
│ - Slack notification │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Test Data Flow
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Test Suite │
|
||||
└──────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Setup Database │
|
||||
│ - Run migrations │
|
||||
│ - Seed test data │
|
||||
└──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Execute Tests │
|
||||
│ - Unit tests │
|
||||
│ - Integration tests │
|
||||
└──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Generate Coverage │
|
||||
│ - coverage-summary │
|
||||
│ - HTML report │
|
||||
└──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Cleanup │
|
||||
│ - Remove test data │
|
||||
│ - Close connections │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Running Tests Locally
|
||||
|
||||
```bash
|
||||
# Quick commands
|
||||
pnpm test # Run all tests
|
||||
pnpm test:cov # Run with coverage
|
||||
pnpm test:seed # Seed test data
|
||||
pnpm test:cleanup # Clean test data
|
||||
|
||||
# Within a package
|
||||
cd services/mana-core-auth
|
||||
pnpm test # Run tests
|
||||
pnpm test:cov # With coverage
|
||||
pnpm test:watch # Watch mode
|
||||
```
|
||||
|
||||
### Triggering Daily Tests Manually
|
||||
|
||||
1. Navigate to GitHub Actions
|
||||
2. Select "Daily Tests" workflow
|
||||
3. Click "Run workflow"
|
||||
4. (Optional) Configure parameters:
|
||||
- Coverage threshold (default: 80%)
|
||||
- Verbose output (default: false)
|
||||
5. Click "Run workflow" button
|
||||
|
||||
### Viewing Test Results
|
||||
|
||||
**Coverage Reports**:
|
||||
- Download from GitHub Actions artifacts
|
||||
- Retention: 30 days
|
||||
- Format: HTML + JSON
|
||||
|
||||
**Aggregated Coverage**:
|
||||
- Download "aggregated-coverage-report" artifact
|
||||
- Retention: 90 days
|
||||
- Includes: `total-coverage.json`, `summary.md`
|
||||
|
||||
**Test Metrics**:
|
||||
- Download "test-metrics" artifact
|
||||
- Retention: 365 days
|
||||
- Includes: `metrics.json`, `metrics-history.json`
|
||||
|
||||
**Flaky Test Reports**:
|
||||
- Download "flaky-test-report" artifact
|
||||
- Retention: 90 days
|
||||
- Format: JSON with failure rates
|
||||
|
||||
## Configuration
|
||||
|
||||
### Coverage Thresholds
|
||||
|
||||
**Global** (all packages):
|
||||
- Lines: 80%
|
||||
- Statements: 80%
|
||||
- Functions: 80%
|
||||
- Branches: 80%
|
||||
|
||||
**Critical Paths** (100% required):
|
||||
- `services/mana-core-auth/src/auth/auth.service.ts`
|
||||
- `services/mana-core-auth/src/credits/credits.service.ts`
|
||||
- `services/mana-core-auth/src/common/guards/jwt-auth.guard.ts`
|
||||
|
||||
### Flaky Test Detection
|
||||
|
||||
- **Threshold**: 10% failure rate
|
||||
- **Minimum Runs**: 3 runs required
|
||||
- **History**: Last 30 runs per test
|
||||
- **Action**: GitHub issue created automatically
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
- **Regression Threshold**: 20% duration increase
|
||||
- **Suite Threshold**: 30% duration increase
|
||||
- **History**: 90 days retained
|
||||
- **Action**: Workflow fails on regression
|
||||
|
||||
## Monitoring and Alerts
|
||||
|
||||
### Automated Notifications
|
||||
|
||||
**GitHub Issues**:
|
||||
- Created on test failure
|
||||
- Created on flaky test detection
|
||||
- Labels: `testing`, `failure`, `flaky-test`, `automated`
|
||||
|
||||
**Slack** (if configured):
|
||||
- Daily test failure notifications
|
||||
- Sent to configured webhook
|
||||
- Includes workflow run link
|
||||
|
||||
### Metrics Dashboard
|
||||
|
||||
Track trends via artifacts:
|
||||
|
||||
1. **Coverage Trends**:
|
||||
- Download aggregated coverage from multiple runs
|
||||
- Compare `total-coverage.json` over time
|
||||
|
||||
2. **Flaky Tests**:
|
||||
- Review `flaky-tests.json` artifact
|
||||
- Track failure rates
|
||||
|
||||
3. **Performance**:
|
||||
- Check `metrics-history.json`
|
||||
- Monitor execution time trends
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing Tests
|
||||
|
||||
✅ **DO**:
|
||||
- Write tests for all new features
|
||||
- Use descriptive test names
|
||||
- Keep tests isolated
|
||||
- Mock external services
|
||||
- Maintain 80%+ coverage
|
||||
|
||||
❌ **DON'T**:
|
||||
- Skip tests for "simple" code
|
||||
- Create order-dependent tests
|
||||
- Make real API calls
|
||||
- Hardcode IDs or timestamps
|
||||
- Commit failing tests
|
||||
|
||||
### Test Data
|
||||
|
||||
✅ **DO**:
|
||||
- Use deterministic test data
|
||||
- Clean up after tests
|
||||
- Use test factories
|
||||
- Seed consistent data
|
||||
|
||||
❌ **DON'T**:
|
||||
- Share state between tests
|
||||
- Use production data
|
||||
- Leave test data behind
|
||||
- Use random values without seeds
|
||||
|
||||
### Coverage
|
||||
|
||||
✅ **DO**:
|
||||
- Aim for high coverage (80%+)
|
||||
- Test critical paths thoroughly
|
||||
- Review coverage reports
|
||||
- Fix coverage drops quickly
|
||||
|
||||
❌ **DON'T**:
|
||||
- Ignore coverage warnings
|
||||
- Write tests just for coverage
|
||||
- Skip edge cases
|
||||
- Rely solely on coverage metrics
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Tests fail with database connection error**:
|
||||
```bash
|
||||
# Solution: Start Docker
|
||||
pnpm docker:up
|
||||
```
|
||||
|
||||
**Coverage below threshold**:
|
||||
```bash
|
||||
# Solution: View uncovered code
|
||||
cd services/mana-core-auth
|
||||
pnpm test:cov
|
||||
open coverage/lcov-report/index.html
|
||||
```
|
||||
|
||||
**Flaky tests detected**:
|
||||
```bash
|
||||
# Solution: Review test isolation
|
||||
# - Check for timing issues
|
||||
# - Verify proper async/await
|
||||
# - Ensure cleanup in afterEach
|
||||
```
|
||||
|
||||
**Performance regression**:
|
||||
```bash
|
||||
# Solution: Profile slow tests
|
||||
# - Check test-results/metrics.json
|
||||
# - Identify slowest tests
|
||||
# - Optimize or split large tests
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Tasks
|
||||
|
||||
**Weekly**:
|
||||
- Review flaky test reports
|
||||
- Address failing tests
|
||||
- Check coverage trends
|
||||
|
||||
**Monthly**:
|
||||
- Review performance metrics
|
||||
- Update test data as needed
|
||||
- Clean up old artifacts
|
||||
|
||||
**Quarterly**:
|
||||
- Audit test coverage
|
||||
- Update testing documentation
|
||||
- Review and improve test quality
|
||||
|
||||
### Updating Scripts
|
||||
|
||||
When modifying reporting scripts:
|
||||
|
||||
1. Test locally with mock data
|
||||
2. Update script README
|
||||
3. Test in workflow with manual trigger
|
||||
4. Monitor first automated run
|
||||
5. Update documentation if needed
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Improvements
|
||||
|
||||
1. **E2E Tests with Playwright**:
|
||||
- Browser-based testing
|
||||
- Visual regression testing
|
||||
- Cross-browser validation
|
||||
|
||||
2. **Test Parallelization**:
|
||||
- Optimize parallel execution
|
||||
- Reduce total workflow time
|
||||
- Smart test splitting
|
||||
|
||||
3. **Coverage Visualization**:
|
||||
- Interactive coverage dashboard
|
||||
- Historical trend charts
|
||||
- Per-developer coverage stats
|
||||
|
||||
4. **Advanced Flaky Detection**:
|
||||
- ML-based prediction
|
||||
- Auto-retry flaky tests
|
||||
- Root cause analysis
|
||||
|
||||
5. **Performance Baselines**:
|
||||
- Establish performance budgets
|
||||
- Block slow test commits
|
||||
- Automated optimization suggestions
|
||||
|
||||
## Support
|
||||
|
||||
### Documentation
|
||||
|
||||
- **Comprehensive Guide**: `/docs/TESTING_GUIDE.md`
|
||||
- **Quick Reference**: `/docs/TESTING_QUICK_REFERENCE.md`
|
||||
- **Script Docs**: `/scripts/test-reporting/README.md`
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **GitHub Issues**: Label with `testing`
|
||||
- **Team Chat**: #testing channel
|
||||
- **Documentation**: Check docs first
|
||||
|
||||
## Metrics and Success Criteria
|
||||
|
||||
### Key Performance Indicators
|
||||
|
||||
| Metric | Target | Current |
|
||||
|--------|--------|---------|
|
||||
| Overall Coverage | 80%+ | TBD (after first run) |
|
||||
| Daily Test Success Rate | 95%+ | TBD |
|
||||
| Flaky Test Count | <5 | TBD |
|
||||
| Average Test Duration | <60s per suite | TBD |
|
||||
| Mean Time to Fix | <24 hours | TBD |
|
||||
|
||||
### Success Criteria
|
||||
|
||||
✅ **Workflow runs successfully daily**
|
||||
✅ **All test suites execute in parallel**
|
||||
✅ **Coverage reports generated and aggregated**
|
||||
✅ **Flaky tests identified and tracked**
|
||||
✅ **Performance metrics recorded**
|
||||
✅ **Failures trigger notifications**
|
||||
✅ **Documentation complete and accessible**
|
||||
|
||||
## Conclusion
|
||||
|
||||
The automated testing system provides comprehensive quality assurance for the ManaCore monorepo with:
|
||||
|
||||
- **Automated Execution**: Daily scheduled runs at 2 AM UTC
|
||||
- **Parallel Testing**: Fast execution across multiple suites
|
||||
- **Coverage Enforcement**: 80% minimum threshold
|
||||
- **Flaky Detection**: Identify unreliable tests
|
||||
- **Performance Tracking**: Monitor test execution trends
|
||||
- **Failure Notifications**: Immediate alerts on issues
|
||||
- **Comprehensive Documentation**: Complete guides and references
|
||||
|
||||
The system is ready for deployment and will ensure continuous quality as the monorepo grows.
|
||||
|
||||
---
|
||||
|
||||
**Implementation**: Hive Mind Swarm (Tester Agent)
|
||||
**Date**: 2025-12-25
|
||||
**Status**: Complete ✅
|
||||
|
|
@ -1,180 +0,0 @@
|
|||
# Dependency Alignment Guide
|
||||
|
||||
This document tracks critical dependencies across all projects and their target versions for alignment.
|
||||
|
||||
## Critical Dependencies
|
||||
|
||||
### High Priority - Version Mismatches
|
||||
|
||||
| Package | Target Version | Current Versions | Notes |
|
||||
| ----------------------- | -------------- | ----------------- | -------------------------------------- |
|
||||
| `@supabase/supabase-js` | **2.81.1** | 2.38.4 - 2.81.1 | Significant spread, alignment critical |
|
||||
| `typescript` | **5.9.2** | 5.3.3 - 5.9.2 | Update all to latest |
|
||||
| `react` | **19.1.0** | 18.3.1 - 19.1.0 | Mixed versions |
|
||||
| `expo` | **54.x** | 52.0.39 - 54.0.21 | Manacore needs update |
|
||||
| `expo-router` | **6.x** | 4.0.19 - 6.0.14 | Manacore needs update |
|
||||
| `astro` | **5.16.0** | 5.3.0 - 5.16.0 | Memoro landing needs update |
|
||||
|
||||
### Current Status by Project
|
||||
|
||||
#### Supabase Versions
|
||||
|
||||
```
|
||||
maerchenzauber:
|
||||
- backend: 2.50.3
|
||||
- mobile: 2.50.3
|
||||
|
||||
manacore:
|
||||
- mobile: 2.38.4 ❌ (very outdated)
|
||||
- web: 2.49.2
|
||||
|
||||
manadeck:
|
||||
- backend: 2.58.0
|
||||
- mobile: 2.38.4 ❌ (very outdated)
|
||||
- web: 2.81.1 ✅
|
||||
|
||||
memoro:
|
||||
- mobile: 2.49.4
|
||||
- web: 2.76.1
|
||||
```
|
||||
|
||||
#### Expo/React Native Versions
|
||||
|
||||
```
|
||||
maerchenzauber:
|
||||
- expo: 54.0.21 ✅
|
||||
- react-native: 0.81.5 ✅
|
||||
- expo-router: 6.0.14 ✅
|
||||
|
||||
manacore:
|
||||
- expo: 52.0.39 ❌ (SDK 52, needs update to 54)
|
||||
- react-native: 0.76.7 ❌
|
||||
- expo-router: 4.0.19 ❌
|
||||
|
||||
manadeck:
|
||||
- expo: 54.0.13 ✅
|
||||
- react-native: 0.81.4 ✅
|
||||
- expo-router: 6.0.10 ✅
|
||||
|
||||
memoro:
|
||||
- expo: 54.0.0 ✅
|
||||
- react-native: 0.81.4 ✅
|
||||
- expo-router: 6.0.8 ✅
|
||||
```
|
||||
|
||||
#### NestJS Versions (Backends)
|
||||
|
||||
```
|
||||
maerchenzauber: NestJS 10.0.0
|
||||
manadeck: NestJS 11.0.1
|
||||
|
||||
Target: Align to NestJS 11.x
|
||||
```
|
||||
|
||||
## Migration Priority
|
||||
|
||||
### Phase 1: Critical Alignments (Week 1)
|
||||
|
||||
1. **Manacore Expo Update** (High Risk)
|
||||
- Upgrade from Expo SDK 52 → 54
|
||||
- Update expo-router 4.x → 6.x
|
||||
- Update react-native 0.76.7 → 0.81.x
|
||||
- This is the most significant update needed
|
||||
|
||||
2. **Supabase Alignment**
|
||||
- Update all projects to 2.81.1
|
||||
- Test auth flows after update
|
||||
- Check for breaking changes in RLS
|
||||
|
||||
3. **TypeScript Alignment**
|
||||
- Update all to 5.9.2
|
||||
- Run type-check across all projects
|
||||
|
||||
### Phase 2: Secondary Alignments (Week 2)
|
||||
|
||||
1. **Astro Updates**
|
||||
- Update Memoro landing from 5.3.0 → 5.16.0
|
||||
|
||||
2. **SvelteKit/Vite Updates**
|
||||
- Align Vite versions (6.0.7 → 7.1.10)
|
||||
- Align SvelteKit versions
|
||||
|
||||
3. **NestJS Alignment**
|
||||
- Update Maerchenzauber backend 10.x → 11.x
|
||||
- Test all API endpoints
|
||||
|
||||
## Alignment Commands
|
||||
|
||||
### Update Supabase across all projects:
|
||||
|
||||
```bash
|
||||
# Maerchenzauber
|
||||
cd maerchenzauber/apps/backend && pnpm update @supabase/supabase-js@2.81.1
|
||||
cd maerchenzauber/apps/mobile && pnpm update @supabase/supabase-js@2.81.1
|
||||
|
||||
# Manacore
|
||||
cd manacore/apps/mobile && pnpm update @supabase/supabase-js@2.81.1
|
||||
cd manacore/apps/web && pnpm update @supabase/supabase-js@2.81.1
|
||||
|
||||
# Manadeck
|
||||
cd manadeck/backend && pnpm update @supabase/supabase-js@2.81.1
|
||||
cd manadeck/apps/mobile && pnpm update @supabase/supabase-js@2.81.1
|
||||
|
||||
# Memoro
|
||||
cd memoro/apps/mobile && pnpm update @supabase/supabase-js@2.81.1
|
||||
cd memoro/apps/web && pnpm update @supabase/supabase-js@2.81.1
|
||||
```
|
||||
|
||||
### Update TypeScript across all projects:
|
||||
|
||||
```bash
|
||||
pnpm update typescript@5.9.2 --recursive
|
||||
```
|
||||
|
||||
## Testing After Alignment
|
||||
|
||||
After updating dependencies, verify:
|
||||
|
||||
1. **Build succeeds**: `pnpm run build`
|
||||
2. **Type checks pass**: `pnpm run type-check`
|
||||
3. **Tests pass**: `pnpm run test`
|
||||
4. **Auth flows work** (especially after Supabase updates)
|
||||
5. **Mobile apps launch** (especially after Expo updates)
|
||||
|
||||
## Breaking Changes to Watch
|
||||
|
||||
### Supabase 2.38 → 2.81
|
||||
|
||||
- Auth session handling may have changed
|
||||
- Check `onAuthStateChange` listeners
|
||||
- Verify RLS policies still work
|
||||
|
||||
### Expo SDK 52 → 54
|
||||
|
||||
- Check expo-router migration guide
|
||||
- New navigation patterns in 6.x
|
||||
- Screen options changes
|
||||
- Layout changes
|
||||
|
||||
### NestJS 10 → 11
|
||||
|
||||
- Decorator changes
|
||||
- Module resolution changes
|
||||
- Check middleware compatibility
|
||||
|
||||
## Recommended Tools
|
||||
|
||||
- **Renovate/Dependabot**: Auto-update dependencies
|
||||
- **pnpm outdated**: Check for outdated packages
|
||||
- **turbo prune**: Create minimal installs for specific projects
|
||||
|
||||
## Tracking Updates
|
||||
|
||||
Mark completed updates:
|
||||
|
||||
- [ ] Supabase alignment (all projects)
|
||||
- [ ] TypeScript alignment (all projects)
|
||||
- [ ] Manacore Expo SDK update
|
||||
- [ ] Astro alignment
|
||||
- [ ] NestJS alignment
|
||||
- [ ] SvelteKit/Vite alignment
|
||||
|
|
@ -1,264 +0,0 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue