till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 18:21:09 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

chore: major cleanup of legacy docs, reports, and unused configs

Browse source 
Deleted 50 files (~26,000 lines):

Root-level legacy reports:
- AUTH_*.md (5 files) - auth architecture reports, now in CLAUDE.md
- TESTING_STRATEGY_*.md, QA_*, TEST_CASES_*.md - old testing plans
- BACKEND_DESIGN_PATTERN_AUDIT.md, COMPATIBILITY_MATRIX_AND_REMEDIATION.md
- HISTORICAL-ANALYSIS.md, MERGE-FIX-SUMMARY.md, RELEASE-PLAN.md
- MANACORE-TODOS.md, APP-IDEAS.md, COMMANDS.md

docs/ cleanup:
- 6 testing docs (duplicates/superseded by .claude/guidelines/testing.md)
- 3 env audit files (canonical: ENVIRONMENT_VARIABLES.md)
- 3 Mac Mini setup docs (canonical: MAC_MINI_SERVER.md)
- 5 daily reports (historical, no ongoing value)
- SELF-HOSTING-GUIDE.md (Coolify/Hetzner based, obsolete)
- CHANGELOG, CONSISTENCY_REPORT, CONSOLIDATION_OPPORTUNITIES, pr-reviews/

.claude/ cleanup:
- audit/ directory (Dec 2025 audit, outdated)
- Speculative plans (MacBook Pro server, Windows GPU server)

Other:
- docker-compose.yml (Traefik-based, replaced by docker-compose.macmini.yml)
- TROUBLESHOOTING.md trimmed (removed 730-line staging deployment section)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Till JS 2026-03-23 10:43:11 +01:00
parent 7c1e2aca49
commit 67a181bb04
50 changed files with 0 additions and 25923 deletions
Download patch file Download diff file Expand all files Collapse all files

631
.claude/audit/ACTION_PLAN_WEEK_1.md
View file

@ -1,631 +0,0 @@
# ⚡ WEEK 1 ACTION PLAN - CRITICAL FIXES
## ManaCore Monorepo Emergency Response
**Timeline:** Days 1-7
**Total Effort:** 17 hours
**Priority:** CRITICAL
**Owner:** DevOps + Backend Team
---
## 🎯 OBJECTIVE
Resolve the 5 most critical issues that pose immediate security, operational, or productivity risks to the monorepo.
**Success Criteria:**
- ✅ No API keys or secrets committed to git
- ✅ PR validation workflow active and blocking broken code
- ✅ Local development setup works for all projects
- ✅ Pre-commit hooks don't take 10+ minutes
- ✅ Database initialization complete and tested
---
## 📋 TASK BREAKDOWN
### TASK 1: REVOKE EXPOSED API KEYS (CRITICAL SECURITY)
**Priority:** 🔴 P0 (DO FIRST)
**Effort:** 2 hours
**Owner:** DevOps Lead
**Risk:** Active API keys exposed in `.env.development` commit history
#### Steps
1. **Immediately revoke these keys** (30 minutes):
```bash
# Google Gemini API
Key: AIzaSyApsYQXxN6PuXpF8-7j6MonCACwS0ZxNRc
Action: Go to https://console.cloud.google.com/apis/credentials
Revoke and generate new key
# Azure OpenAI API
Key: 3082103c9b0d4270a795686ccaa89921
Action: Go to Azure Portal → Cognitive Services → Regenerate key
# WorldDream OpenAI
Key: sk-proj-qdYUVUqNv...
Action: Go to OpenAI Platform → API Keys → Revoke
# WorldDream Gemini
Key: AIzaSyB74aUj1KmJlcjNyT5uUiyDODQ6iYoAOjQ
Action: Revoke via Google Cloud Console
# Replicate API
Key: r8_QlvkstNhIc6NBX1ktpQ6ibvzOE2d2UQ1Emamd
Action: Go to https://replicate.com/account → Revoke
```
2. **Audit API usage logs** (30 minutes):
- Check for unauthorized usage in the last 30 days
- Document any suspicious activity
- Calculate potential exposure cost
3. **Generate new keys** (30 minutes):
- Create new keys for all services
- Store in password manager (1Password/LastPass)
- Document key rotation process
4. **Update local environments** (30 minutes):
- Create `.env.development.local` with new keys
- Share securely with team (encrypted)
- Test all services with new keys
#### Verification
```bash
# Ensure no secrets in tracked files
git grep "AIza" -- '*.env*' '!*.local' # Should return nothing
git grep "sk-proj" -- '*.env*' '!*.local' # Should return nothing
# Verify local setup works
pnpm docker:up
pnpm setup:env
pnpm run chat:dev # Test with new keys
```
#### Files Changed
- `.env.development` - Remove all real keys, add placeholders
- `.env.development.local` - Create with new keys (gitignored)
- `.env.development.example` - Create template for onboarding
---
### TASK 2: IMPLEMENT SECRETS MANAGEMENT
**Priority:** 🔴 P0
**Effort:** 8 hours
**Owner:** DevOps Lead
**Goal:** Never commit secrets to git again
#### Steps
1. **Update `.gitignore`** (15 minutes):
```bash
# Add to root .gitignore
.env.development.local
.env.production.local
.env.staging.local
.env*.local
```
2. **Update `scripts/generate-env.mjs`** (2 hours):
```javascript
// Read from .local files if they exist, otherwise use .env.development
import fs from 'fs';
import path from 'path';
function loadEnvFile(filename) {
const localPath = filename.replace('.development', '.development.local');
if (fs.existsSync(localPath)) {
console.log(`Using ${localPath} (secrets file)`);
return dotenv.parse(fs.readFileSync(localPath));
}
console.log(`Using ${filename} (template file)`);
return dotenv.parse(fs.readFileSync(filename));
}
const sourceEnv = {
...loadEnvFile('.env.development'),
...loadEnvFile('.env.development.local'), // Override with secrets
};
```
3. **Add environment variable validation** (3 hours):
```bash
pnpm add -D zod
```
```javascript
// scripts/validate-env.mjs
import { z } from 'zod';
const envSchema = z.object({
MANA_CORE_AUTH_URL: z.string().url(),
POSTGRES_PASSWORD: z.string().min(8),
GOOGLE_GENAI_API_KEY: z.string().startsWith('AIza').optional(),
AZURE_OPENAI_API_KEY: z.string().min(20).optional(),
// ... all required vars
});
export function validateEnv(env) {
const result = envSchema.safeParse(env);
if (!result.success) {
console.error('❌ Invalid environment variables:');
console.error(result.error.format());
process.exit(1);
}
console.log('✅ Environment variables validated');
}
```
4. **Create setup script** (1 hour):
```bash
# scripts/setup-secrets.sh
#!/bin/bash
echo "🔐 Setting up secrets for manacore-monorepo"
if [ ! -f .env.development.local ]; then
echo "Creating .env.development.local from example..."
cp .env.development.example .env.development.local
echo "⚠️ Please fill in your API keys in .env.development.local"
exit 1
fi
echo "✅ Secrets file exists"
node scripts/generate-env.mjs
```
5. **Update documentation** (1 hour):
```markdown
# docs/SECRETS_MANAGEMENT.md
## Never Commit Secrets
1. All API keys go in `.env.development.local` (gitignored)
2. Template values in `.env.development.example`
3. Production secrets in GitHub Secrets or Vault
## First-Time Setup
bash
cp .env.development.example .env.development.local
# Edit .env.development.local with your keys
pnpm setup:env
```
6. **Test setup** (1 hour):
```bash
# Fresh clone simulation
rm -rf node_modules .env*
cp .env.development.example .env.development.local
# Add test keys
pnpm install
pnpm setup:env
pnpm docker:up
pnpm run chat:dev
```
#### Files Changed
- `.gitignore` - Add `.env*.local`
- `scripts/generate-env.mjs` - Support `.local` files
- `scripts/validate-env.mjs` - NEW (validation)
- `scripts/setup-secrets.sh` - NEW (onboarding)
- `.env.development.example` - NEW (template)
- `.env.development.local` - NEW (gitignored secrets)
- `docs/SECRETS_MANAGEMENT.md` - NEW (documentation)
---
### TASK 3: FIX DATABASE INITIALIZATION
**Priority:** 🔴 P0
**Effort:** 2 hours
**Owner:** Backend Lead
**Goal:** Complete local dev setup with one command
#### Steps
1. **Audit required databases** (30 minutes):
```bash
# Extract all DATABASE_URL from .env.development
grep "DATABASE_URL" .env.development | grep -o "localhost:5432/[^\"]*" | cut -d'/' -f2 | sort -u
```
2. **Update initialization script** (1 hour):
```sql
-- docker/init-db/01-create-databases.sql
-- Existing (keep these)
CREATE DATABASE chat;
CREATE DATABASE voxel_lava;
CREATE DATABASE storage;
CREATE DATABASE todo;
-- Add missing databases
CREATE DATABASE manacore;
CREATE DATABASE zitare;
CREATE DATABASE presi;
CREATE DATABASE contacts;
CREATE DATABASE calendar;
CREATE DATABASE manadeck;
CREATE DATABASE finance;
CREATE DATABASE moodlit;
CREATE DATABASE moods;
CREATE DATABASE picture;
CREATE DATABASE nutriphi;
CREATE DATABASE quote;
CREATE DATABASE clock;
CREATE DATABASE context;
-- Grant privileges to all databases
DO $$
DECLARE
db_name TEXT;
BEGIN
FOR db_name IN
SELECT datname FROM pg_database
WHERE datname NOT IN ('postgres', 'template0', 'template1')
LOOP
EXECUTE format('GRANT ALL PRIVILEGES ON DATABASE %I TO manacore', db_name);
END LOOP;
END $$;
```
3. **Test fresh setup** (30 minutes):
```bash
# Teardown existing
pnpm docker:down
docker volume rm manacore-monorepo_postgres_data
# Fresh start
pnpm docker:up
# Verify all databases exist
docker exec -it manacore-postgres psql -U manacore -c "\l" | grep manacore
# Should show all 17+ databases
```
#### Files Changed
- `docker/init-db/01-create-databases.sql` - Add all missing databases
#### Verification Checklist
- [ ] All databases from `.env.development` are created
- [ ] `manacore` user has access to all databases
- [ ] Fresh `pnpm docker:up` creates all databases
- [ ] `pnpm run chat:dev` connects successfully
- [ ] No manual database creation needed
---
### TASK 4: ENABLE CI PR VALIDATION
**Priority:** 🔴 P0
**Effort:** 4 hours
**Owner:** DevOps Lead
**Goal:** Block broken code from merging to main
#### Steps
1. **Restore PR workflow** (30 minutes):
```bash
mv .github/workflows/ci-pull-request.yml.bak .github/workflows/ci-pull-request.yml
```
2. **Update workflow** (2 hours):
```yaml
# .github/workflows/ci-pull-request.yml
name: CI - Pull Request Validation
on:
pull_request:
branches: [main, dev]
jobs:
validate:
name: Code Quality Checks
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup pnpm
uses: pnpm/action-setup@v2
with:
version: 9.15.0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Format check
run: pnpm format:check
- name: Lint
run: pnpm lint
- name: Type check
run: pnpm type-check
timeout-minutes: 10
# Uncomment when tests exist
# - name: Test
# run: pnpm test
# timeout-minutes: 15
# - name: Upload coverage
# uses: codecov/codecov-action@v3
# with:
# files: ./coverage/lcov.info
security:
name: Security Scan
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run npm audit
run: |
pnpm audit --prod --audit-level=high
# Don't fail on audit issues yet (too many)
continue-on-error: true
```
3. **Add branch protection rules** (1 hour):
- Go to GitHub repo → Settings → Branches
- Add rule for `main` and `dev`:
- ✅ Require status checks to pass
- ✅ Require `validate` job to pass
- ✅ Require up-to-date branches
- ✅ Include administrators
4. **Test workflow** (30 minutes):
```bash
# Create test PR
git checkout -b test/ci-validation
echo "test" >> README.md
git add README.md
git commit -m "test: CI validation"
git push origin test/ci-validation
# Create PR on GitHub
# Verify workflow runs
# Verify PR blocked if checks fail
```
#### Files Changed
- `.github/workflows/ci-pull-request.yml` - Restored and updated
- GitHub branch protection rules (via UI)
#### Verification Checklist
- [ ] PR workflow runs on new PRs
- [ ] Format check fails on bad formatting
- [ ] Lint check fails on linting errors
- [ ] Type check completes in <10 minutes
- [ ] PR cannot be merged if checks fail
---
### TASK 5: FIX PRE-COMMIT HOOK PERFORMANCE
**Priority:** 🟡 P1
**Effort:** 1 hour
**Owner:** DevOps Lead
**Goal:** Pre-commit takes <30 seconds (not 10+ minutes)
#### Steps
1. **Update pre-commit hook** (30 minutes):
```bash
# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
# Run lint-staged (only on changed files)
pnpm exec lint-staged
# REMOVED: pnpm run type-check (too slow, move to CI)
```
2. **Update lint-staged config** (30 minutes):
```json
// package.json
{
"lint-staged": {
"*.{ts,tsx,js,jsx}": [
"eslint --fix --max-warnings=0",
"prettier --write"
],
"*.{json,md,yml,yaml}": [
"prettier --write"
],
"*.{svelte}": [
"eslint --fix --max-warnings=0",
"prettier --plugin prettier-plugin-svelte --write"
],
"*.{astro}": [
"prettier --plugin prettier-plugin-astro --write"
]
}
}
```
#### Files Changed
- `.husky/pre-commit` - Remove global type-check
- `package.json` - Update lint-staged config
#### Verification
```bash
# Make a small change
echo "// test" >> apps/chat/apps/backend/src/main.ts
# Stage and commit
git add apps/chat/apps/backend/src/main.ts
time git commit -m "test: pre-commit performance"
# Should complete in <30 seconds
```
---
## 📊 PROGRESS TRACKING
### Daily Standup Template
**Day 1 (Security Crisis Day):**
- [ ] TASK 1: Revoke exposed API keys (2h)
- [ ] TASK 2: Start secrets management (4h/8h)
**Day 2 (Security Completion):**
- [ ] TASK 2: Finish secrets management (4h/8h)
- [ ] TASK 3: Fix database initialization (2h)
**Day 3 (CI/CD Setup):**
- [ ] TASK 4: Enable CI PR validation (4h)
- [ ] TASK 5: Fix pre-commit performance (1h)
**Day 4 (Testing & Verification):**
- [ ] Test all fixes
- [ ] Update documentation
- [ ] Team demo
### Verification Commands
```bash
# Security verification
git log --all --full-history -- .env.development | grep -i "api.*key" # Should be empty in new commits
grep -r "AIza\|sk-proj" .env* --exclude="*.local" --exclude="*.example" # Should be empty
# Database verification
docker exec -it manacore-postgres psql -U manacore -c "\l" | wc -l # Should show 17+ databases
# CI verification
gh pr checks <pr-number> # All checks should pass
# Pre-commit verification
time git commit --allow-empty -m "test" # Should be <30s
```
---
## 🎯 SUCCESS METRICS
### Week 1 Goals
| Metric | Before | Target | Actual |
|--------|--------|--------|--------|
| Secrets in git | ✅ Yes (CRITICAL) | ❌ No | ___ |
| PR validation | ❌ Disabled | ✅ Active | ___ |
| Database setup time | 2+ hours (manual) | 5 minutes (automated) | ___ |
| Pre-commit duration | 10+ minutes | <30 seconds | ___ |
| Local dev setup | Broken for new devs | One-command setup | ___ |
### Definition of Done
- [ ] ✅ All API keys revoked and rotated
- [ ] ✅ Secrets in `.env.development.local` (gitignored)
- [ ] ✅ Environment validation script works
- [ ] ✅ Fresh `git clone` + `pnpm install` sets up everything
- [ ] ✅ All 17+ databases created on `pnpm docker:up`
- [ ] ✅ PR workflow active and blocking broken code
- [ ] ✅ Pre-commit hook completes in <30s
- [ ] ✅ Documentation updated
- [ ] ✅ Team trained on new workflow
---
## 📚 DOCUMENTATION UPDATES
### Files to Update
1. **ROOT README.md:**
```markdown
## First-Time Setup
1. Clone the repository
2. Copy `.env.development.example` to `.env.development.local`
3. Fill in your API keys in `.env.development.local`
4. Run `pnpm install`
5. Run `pnpm docker:up`
6. Start developing: `pnpm run chat:dev`
**IMPORTANT:** Never commit `.env.development.local` - it contains secrets!
```
2. **docs/ENVIRONMENT_VARIABLES.md:**
- Add section on secrets management
- Explain `.local` file pattern
- Document validation process
3. **CLAUDE.md:**
- Update environment variables section
- Add security best practices
- Document CI/CD workflow
---
## 🚨 ROLLBACK PLAN
If anything goes wrong:
1. **API Keys Broken:**
```bash
# Restore from password manager
# Update .env.development.local
pnpm setup:env
```
2. **Database Init Broken:**
```bash
# Restore old SQL file from git
git checkout HEAD~1 docker/init-db/01-create-databases.sql
pnpm docker:down
pnpm docker:up
```
3. **CI Workflow Broken:**
```bash
# Disable workflow temporarily
mv .github/workflows/ci-pull-request.yml .github/workflows/ci-pull-request.yml.bak
git add .github/workflows/ci-pull-request.yml.bak
git commit -m "fix: disable CI temporarily"
```
---
## 🎓 POST-WEEK 1 RETROSPECTIVE
### Questions to Answer
1. What went well?
2. What took longer than expected?
3. What did we learn about our system?
4. What should we prioritize next?
5. How can we prevent similar issues?
### Next Steps Planning
- Review Week 2-4 action plan (testing foundation)
- Allocate resources for testing sprint
- Set up coverage tracking
- Schedule daily standups for testing work
---
**END OF WEEK 1 ACTION PLAN**
*Priority: CRITICAL*
*Total Effort: 17 hours*
*Timeline: Days 1-7*
*Success Criteria: All tasks completed and verified*

145
.claude/audit/AUDIT_SUMMARY.md
View file

@ -1,145 +0,0 @@
# Documentation Audit Summary
**Date:** 2025-12-07
**Full Report:** [documentation-audit-2025-12-07.md](./documentation-audit-2025-12-07.md)
## Quick Stats
- **Active Projects:** 17 (apps/) + 5 (games/) + 1 (service)
- **Documentation Coverage:** 11/17 active projects have CLAUDE.md
- **Critical Issues:** 3
- **Overall Score:** 7/10
## Top 3 Critical Issues
### 1. 🚨 Active vs Archived Confusion
**5 projects exist in BOTH `apps/` and `apps-archived/`:**
- maerchenzauber
- memoro
- wisekeep
- reader
- nutriphi
Root CLAUDE.md lists them as archived, but they're in the active workspace.
### 2. ❌ Missing Major Project Documentation
**No CLAUDE.md files for:**
- **manadeck** (major project with full stack)
- **picture** (AI image generation)
- **quote** (backend + web + mobile)
- Several other active projects
### 3. 📝 Incomplete Root Documentation
**Root CLAUDE.md only documents 6/17 active projects:**
- Missing: calendar, clock, context, todo, quote, and 6+ others
- Outdated commands (presi:dev, mail:dev for archived projects)
## Immediate Action Items
1. ✅ **Resolve duplicates** - Decide on maerchenzauber, memoro, wisekeep, reader, nutriphi status
2. ✅ **Create CLAUDE.md** for manadeck and picture (high priority)
3. ✅ **Update root CLAUDE.md** with complete project list (17 projects)
4. ✅ **Fix commands** - Remove presi:dev, mail:dev; add calendar:dev, clock:dev, todo:dev
5. ✅ **Backend ports table** - Document all 12 backends with port numbers
## Documentation Quality by Project
### Excellent (10/10)
- ✅ calendar (German, comprehensive)
- ✅ clock (German, comprehensive)
- ✅ todo (German, comprehensive)
### Good (8-9/10)
- ✅ chat
- ✅ contacts
- ✅ context
- ✅ zitare
### Missing
- ❌ manadeck
- ❌ picture
- ❌ quote
- ❌ 8+ other projects
## Key Findings
### Projects Not in Root Docs
Missing from root CLAUDE.md but active:
- calendar (port 3014)
- clock (port 3017)
- context (mobile only)
- todo (port 3018)
- quote (full stack)
- maerchenzauber* (duplicate)
- memoro* (duplicate)
- nutriphi* (duplicate)
- reader* (duplicate)
- wisekeep* (duplicate)
### Landing Pages Mismatch
- **Actual:** 7 landing pages (chat, picture, manacore, manadeck, zitare, calendar, clock)
- **Documented:** 5 (missing calendar, clock)
- **Deploy scripts:** 10 (includes non-existent: presi, mail, moodlit)
### Shared Packages Gap
- **Actual:** 34 packages
- **Documented:** 10 packages
- **Missing:** 24 packages undocumented
## Priority Matrix
| Issue | Priority | Impact | Effort |
|-------|----------|--------|--------|
| Resolve active/archived confusion | 🔴 HIGH | Critical | Medium |
| Create manadeck CLAUDE.md | 🔴 HIGH | High | Low |
| Create picture CLAUDE.md | 🔴 HIGH | High | Low |
| Update root projects table | 🔴 HIGH | High | Low |
| Backend ports reference | 🟡 MEDIUM | Medium | Low |
| Landing pages docs fix | 🟡 MEDIUM | Medium | Low |
| Shared packages docs | 🟡 MEDIUM | Medium | High |
| Games section | 🟢 LOW | Low | Low |
## Recommendations
### Week 1
- Resolve duplicate projects (remove from apps/ OR apps-archived/)
- Create CLAUDE.md for manadeck, picture
- Update root CLAUDE.md with all 17 active projects
### Week 2-4
- Document all backend ports
- Fix landing pages section
- Update environment variables docs
- Add games overview
### Ongoing
- Create CLAUDE.md for all remaining projects
- Automated documentation validation
- Version compatibility matrix
## Files to Review/Update
1. `/CLAUDE.md` - Add missing projects, fix commands
2. `/apps/manadeck/CLAUDE.md` - CREATE
3. `/apps/picture/CLAUDE.md` - CREATE
4. `/docs/ENVIRONMENT_VARIABLES.md` - Add missing projects
5. `/package.json` - Clean up commands for archived projects
## Success Metrics
**Target Documentation Coverage:**
- ✅ 100% of active projects in root CLAUDE.md
- ✅ 100% of active projects have project CLAUDE.md
- ✅ All backend ports documented
- ✅ Landing pages list is accurate
- ✅ No duplicate projects between apps/ and apps-archived/
**Current Status:**
- ⚠️ 35% of active projects in root docs (6/17)
- ⚠️ 65% have project CLAUDE.md (11/17)
- ⚠️ 42% of backends documented (5/12)
- ⚠️ Landing pages 71% accurate (5/7)
- ❌ 5 duplicate projects
---
**Next Steps:** Review full audit report and prioritize fixes based on your team's needs.

317
.claude/audit/FIXES_CHECKLIST.md
View file

@ -1,317 +0,0 @@
# Documentation Fixes Checklist
**Generated:** 2025-12-07
**Status:** Ready for implementation
Use this checklist to systematically fix all documentation issues identified in the audit.
---
## Phase 1: Critical Fixes (Week 1)
### 🚨 Issue 1: Resolve Active/Archived Confusion
**5 projects in BOTH apps/ and apps-archived/:**
- [ ] **maerchenzauber** - Decide: Keep in apps/ OR apps-archived/
- [ ] If keeping in apps/: Delete from apps-archived/
- [ ] If archiving: Delete from apps/
- [ ] Update root CLAUDE.md archived projects list
- [ ] Update pnpm-workspace.yaml if needed
- [ ] **memoro** - Decide: Keep in apps/ OR apps-archived/
- [ ] If keeping in apps/: Delete from apps-archived/
- [ ] If archiving: Delete from apps/
- [ ] Update root CLAUDE.md archived projects list
- [ ] **wisekeep** - Decide: Keep in apps/ OR apps-archived/
- [ ] If keeping in apps/: Delete from apps-archived/
- [ ] If archiving: Delete from apps/
- [ ] Update root CLAUDE.md archived projects list
- [ ] **reader** - Decide: Keep in apps/ OR apps-archived/
- [ ] If keeping in apps/: Delete from apps-archived/
- [ ] If archiving: Delete from apps/
- [ ] Update root CLAUDE.md archived projects list
- [ ] **nutriphi** - Decide: Keep in apps/ OR apps-archived/
- [ ] If keeping in apps/: Delete from apps-archived/
- [ ] If archiving: Delete from apps/
- [ ] Update root CLAUDE.md archived projects list
### ❌ Issue 2: Create Missing Major Project Docs
- [ ] **Create `/apps/manadeck/CLAUDE.md`**
- [ ] Document backend (port 3009)
- [ ] Document web app
- [ ] Document mobile app
- [ ] Document landing page
- [ ] Add API endpoints
- [ ] Add database schema
- [ ] Add development commands
- [ ] Add environment variables
- [ ] **Create `/apps/picture/CLAUDE.md`**
- [ ] Document backend (port 3006)
- [ ] Document web app
- [ ] Document mobile app
- [ ] Document landing page
- [ ] Add AI image generation details
- [ ] Add API endpoints
- [ ] Add development commands
- [ ] Add environment variables
- [ ] **Create `/apps/quote/CLAUDE.md`**
- [ ] Document backend
- [ ] Document web app
- [ ] Document mobile app
- [ ] Add API endpoints
- [ ] Add development commands
### 📝 Issue 3: Update Root CLAUDE.md
**File:** `/CLAUDE.md`
- [ ] **Update Projects Table (lines 31-40)**
```markdown
| Project | Description | Apps |
| ------------ | ---------------------------- | --------------------------------------------------------- |
| **manacore** | Multi-app ecosystem platform | Expo mobile, SvelteKit web, Astro landing |
| **manadeck** | Card/deck management | NestJS backend, Expo mobile, SvelteKit web, Astro landing|
| **picture** | AI image generation | NestJS backend, Expo mobile, SvelteKit web, Astro landing|
| **chat** | AI chat application | NestJS backend, Expo mobile, SvelteKit web, Astro landing|
| **zitare** | Daily inspiration quotes | NestJS backend, Expo mobile, SvelteKit web, Astro landing|
| **contacts** | Contact management | NestJS backend, SvelteKit web |
| **calendar** | Calendar & scheduling | NestJS backend, SvelteKit web, Astro landing |
| **clock** | World clock & timers | NestJS backend, SvelteKit web, Astro landing |
| **todo** | Task management | NestJS backend, SvelteKit web |
| **context** | AI document management | Expo mobile |
| **quote** | Quote management | NestJS backend, SvelteKit web, Expo mobile |
```
- [ ] **Add missing projects** to table (after resolving duplicates)
- [ ] **Update Development Commands (lines 61-76)**
```bash
# Start specific project (runs all apps in project)
pnpm run manacore:dev
pnpm run manadeck:dev
pnpm run picture:dev
pnpm run chat:dev
pnpm run zitare:dev
pnpm run contacts:dev
pnpm run calendar:dev # ADD
pnpm run clock:dev # ADD
pnpm run todo:dev # ADD
pnpm run context:dev # ADD
# REMOVE: pnpm run presi:dev
# REMOVE: pnpm run mail:dev
```
- [ ] **Update Integrated Backends Table (lines 334-342)**
```markdown
| Backend | Package | Port |
| -------- | ------------------------------- | ---- |
| Chat | `@mana-core/nestjs-integration` | 3002 |
| Picture | `@manacore/shared-nestjs-auth` | 3006 |
| Zitare | `@manacore/shared-nestjs-auth` | 3007 |
| ManaDeck | `@mana-core/nestjs-integration` | 3009 |
| Calendar | `@manacore/shared-nestjs-auth` | 3014 | # ADD
| Contacts | `@manacore/shared-nestjs-auth` | 3015 | # ADD
| Clock | `@manacore/shared-nestjs-auth` | 3017 | # ADD
| Todo | `@manacore/shared-nestjs-auth` | 3018 | # ADD
# REMOVE: | Presi | Custom (same pattern) | 3008 |
```
- [ ] **Update Landing Pages Table (lines 470-476)**
```markdown
| Project | Package | Cloudflare Project | URL |
|---------|---------|-------------------|-----|
| Chat | `@chat/landing` | `chat-landing` | https://chat-landing.pages.dev |
| Picture | `@picture/landing` | `picture-landing` | https://picture-landing.pages.dev |
| ManaCore | `@manacore/landing` | `manacore-landing` | https://manacore-landing.pages.dev |
| ManaDeck | `@manadeck/landing` | `manadeck-landing` | https://manadeck-landing.pages.dev |
| Zitare | `@zitare/landing` | `zitare-landing` | https://zitare-landing.pages.dev |
| Calendar | `@calendar/landing` | `calendar-landing` | https://calendar-landing.pages.dev | # ADD
| Clock | `@clock/landing` | `clock-landing` | https://clock-landing.pages.dev | # ADD
```
- [ ] **Update Archived Projects List (lines 42-59)**
- [ ] Add/remove based on Phase 1 duplicate resolution
- [ ] Add missing: finance, mail, moodlit
- [ ] Remove duplicates that were moved to active
- [ ] **Add Games Section** (new section after Projects)
```markdown
### Game Projects (`games/`)
| Project | Description | Status |
| ------------ | ------------------------ | ------ |
| **figgos** | [Description] | Active |
| **mana-games** | [Description] | Active |
| **voxelava** | [Description] | Active |
| **whopixels** | [Description] | Active |
| **worldream** | [Description] | Active |
```
---
## Phase 2: High Priority Fixes (Week 2)
### Update Root CLAUDE.md (continued)
- [ ] **Expand Shared Packages Section (lines 361-381)**
- [ ] Add missing packages (24 undocumented)
- [ ] OR: Add note: "See `/packages/README.md` for complete list"
- [ ] OR: Create table with all 34 packages
### Update Environment Variables Documentation
**File:** `/docs/ENVIRONMENT_VARIABLES.md`
- [ ] Add calendar environment variables
- [ ] Add clock environment variables
- [ ] Add contacts environment variables
- [ ] Add todo environment variables
- [ ] Add quote environment variables
- [ ] Add context environment variables
- [ ] Update table of contents
- [ ] Verify all variables match actual .env files
### Clean Up package.json
**File:** `/package.json`
- [ ] **Remove invalid deploy scripts (lines 154-157)**
- [ ] Remove: `"deploy:landing:presi"` (landing doesn't exist)
- [ ] Remove: `"deploy:landing:mail"` (landing doesn't exist)
- [ ] Remove: `"deploy:landing:moodlit"` (landing doesn't exist)
- [ ] **Update deploy:landing:all script (line 158)**
- [ ] Remove presi, mail, moodlit
- [ ] Add calendar, clock if not present
---
## Phase 3: Medium Priority (Weeks 3-4)
### Create Additional Project Documentation
- [ ] **Create `/apps/context/README.md`** (expand beyond CLAUDE.md)
- [ ] **Review/update `/apps/manacore/CLAUDE.md`**
- [ ] **Review/update `/services/mana-core-auth/CLAUDE.md`**
### Create Shared Packages Documentation
- [ ] **Create `/packages/README.md`**
- [ ] List all 34 packages
- [ ] Describe purpose of each
- [ ] Show import patterns
- [ ] Document inter-package dependencies
### Update .claude Guidelines
**Files in `.claude/guidelines/`**
- [ ] Review authentication.md for accuracy
- [ ] Review database.md - add missing projects
- [ ] Review nestjs-backend.md - add all backends
- [ ] Review expo-mobile.md - add all mobile apps
- [ ] Review sveltekit-web.md - add all web apps
### Create Missing Documentation
- [ ] **Create `/docs/BACKENDS.md`**
- [ ] Table of all backends
- [ ] Ports, technologies, database
- [ ] Dependencies
- [ ] **Create `/docs/LANDING_PAGES.md`**
- [ ] Deployment workflow
- [ ] Cloudflare setup
- [ ] All landing pages
- [ ] **Update `/docs/PROJECT_OVERVIEW.md`**
- [ ] Ensure all active projects listed
- [ ] Update statistics
---
## Phase 4: Low Priority (Future)
### Automation & Validation
- [ ] **Create `/scripts/validate-docs.mjs`**
- [ ] Check all apps/ have CLAUDE.md
- [ ] Verify ports in docs match actual configs
- [ ] Check package.json commands exist for all projects
- [ ] Validate landing pages exist where documented
- [ ] **Create `/scripts/generate-project-list.mjs`**
- [ ] Auto-generate projects table from filesystem
- [ ] Output markdown table
- [ ] Can be used to update root CLAUDE.md
### Version Documentation
- [ ] **Create `/docs/VERSIONS.md`**
- [ ] React Native version per mobile app
- [ ] Expo SDK version per mobile app
- [ ] NestJS version per backend
- [ ] SvelteKit version per web app
- [ ] Node.js compatibility
### Testing Documentation
- [ ] Verify all curl examples in CLAUDE.md files work
- [ ] Test all pnpm commands documented
- [ ] Validate all environment variables exist
---
## Verification Checklist
After completing fixes, verify:
- [ ] All 17 active projects are in root CLAUDE.md
- [ ] All 17 active projects have CLAUDE.md files
- [ ] No projects exist in both apps/ and apps-archived/
- [ ] All backend ports are documented
- [ ] All landing pages are accurately documented
- [ ] All pnpm commands work
- [ ] Landing deploy scripts match actual landing pages
- [ ] Archived projects list matches apps-archived/
- [ ] Games section exists with all 5 games
- [ ] Environment variables docs cover all active projects
---
## Progress Tracking
**Started:** [DATE]
**Phase 1 Complete:** [DATE]
**Phase 2 Complete:** [DATE]
**Phase 3 Complete:** [DATE]
**Phase 4 Complete:** [DATE]
**Issues Resolved:** 0/12
### Phase Completion
- [ ] Phase 1: Critical Fixes (3 issues)
- [ ] Phase 2: High Priority (4 issues)
- [ ] Phase 3: Medium Priority (3 issues)
- [ ] Phase 4: Low Priority (2 issues)
---
## Notes
Add any notes about decisions made or blockers encountered:
-
-
-
---
**Tip:** Use this checklist with GitHub issues or a project management tool by converting each section to a separate issue/task.

458
.claude/audit/HIVE_MIND_EXECUTIVE_SUMMARY.md
View file

@ -1,458 +0,0 @@
# 🧠 HIVE MIND COLLECTIVE INTELLIGENCE REPORT
## ManaCore Monorepo - Comprehensive Audit & Improvement Plan
**Swarm ID:** swarm-1765095736318-q124en9du
**Swarm Name:** hive-1765095736313
**Audit Date:** 2025-12-07
**Queen Coordinator:** Strategic Analysis Agent
**Worker Agents:** 4 (Researcher, Coder, Analyst, Tester)
---
## 🎯 EXECUTIVE SUMMARY
The hive mind collective has completed a comprehensive audit of the manacore-monorepo across four critical dimensions: **Documentation, Code Quality, Architecture, and Testing**. The consensus assessment reveals a project with **strong architectural foundations** but **critical gaps in quality assurance, testing, and operational readiness**.
### Overall Assessment Matrix
| Dimension | Score | Status | Priority |
|-----------|-------|--------|----------|
| **Architecture & Design** | 90/100 | ✅ Excellent | Maintain |
| **Documentation** | 70/100 | 🟡 Good | Improve |
| **Code Quality** | 70/100 | 🟡 Good | Improve |
| **Testing Coverage** | 10/100 | 🔴 Critical | **URGENT** |
| **CI/CD & DevOps** | 40/100 | 🔴 Poor | **URGENT** |
| **Security** | 50/100 | 🔴 Poor | **URGENT** |
**Overall Monorepo Health:** **60/100** (C grade - Functional but High Risk)
---
## 🚨 CRITICAL FINDINGS (Requires Immediate Action)
### 1. **SECURITY BREACH: API Keys Exposed in Git** 🔴
**Severity:** CRITICAL
**Impact:** Active API keys committed to `.env.development`
**Risk:** Unauthorized usage, data breach, financial loss
**Exposed Keys:**
- Google Gemini API Key
- Azure OpenAI API Key
- Replicate API Token
- WorldDream API Keys (OpenAI, Gemini)
**IMMEDIATE ACTIONS REQUIRED:**
1. ✅ Revoke all exposed keys within 24 hours
2. ✅ Move to `.env.development.local` (gitignored)
3. ✅ Rotate all production secrets
4. ✅ Audit API usage for unauthorized access
5. ✅ Implement secrets management (Doppler/Vault)
**Files to Fix:**
- `.env.development` - Remove all real keys
- Create `.env.development.example` with placeholders
- Update `scripts/generate-env.mjs` to read from `.local` files
---
### 2. **TESTING CATASTROPHE: <1% Coverage** 🔴
**Severity:** CRITICAL
**Impact:** No automated quality assurance for 99% of codebase
**Risk:** Production bugs, regression failures, customer impact
**Key Metrics:**
- **Total Test Files:** 23 (only in mana-core-auth)
- **Backends Tested:** 1/12 (8% coverage)
- **Mobile Apps Tested:** 0/7 (0% coverage)
- **Web Apps Tested:** 0/7 (0% coverage)
- **Shared Packages Tested:** 0/37 (0% coverage)
**Critical Untested Areas:**
- 🔴 **Authentication integration** - All backends use mana-core-auth but none test it
- 🔴 **Credit consumption** - Billing logic has zero tests (double-charging risk!)
- 🔴 **Storage operations** - S3 uploads/downloads untested (data loss risk)
- 🔴 **API endpoints** - 100+ endpoints have no tests
**IMMEDIATE ACTIONS REQUIRED:**
1. ✅ Test `@manacore/shared-nestjs-auth` (security critical)
2. ✅ Test `@manacore/shared-storage` (data integrity)
3. ✅ Test credit consumption flows (billing accuracy)
4. ✅ Add tests to chat, picture, zitare backends
5. ✅ Enable CI test validation on PRs
**Estimated Effort:** 460-660 hours (3-4 months full-time)
---
### 3. **BUILD PERFORMANCE: 10x Slower Than Expected** 🔴
**Severity:** HIGH
**Impact:** Type-check takes 10+ minutes (should be 1-2 minutes)
**Risk:** Developer productivity loss, CI timeouts
**Root Cause:** ~~Recursive turbo calls in parent packages~~
**UPDATE:** ✅ **FALSE ALARM** - After analysis, parent packages only contain `dev` scripts, which is acceptable per guidelines. The actual cause of slow builds needs further investigation (likely high concurrency limit or other factors).
**ACTIONS:**
1. ✅ Investigate actual slow build cause (not turbo recursion)
2. ✅ Test with higher concurrency (`"concurrency": "10"`)
3. ✅ Enable Turborepo remote caching
4. ✅ Profile build performance
---
### 4. **DATABASE INITIALIZATION INCOMPLETE** 🔴
**Severity:** HIGH
**Impact:** Developers cannot set up local environment
**Risk:** Onboarding friction, inconsistent dev environments
**Current State:** `docker/init-db/01-create-databases.sql` only creates 5 databases
**Missing:** 12+ databases (zitare, presi, contacts, calendar, manadeck, finance, moodlit, etc.)
**IMMEDIATE ACTIONS REQUIRED:**
1. ✅ Update `01-create-databases.sql` with all databases from `.env.development`
2. ✅ Add grant statements for all databases
3. ✅ Test fresh Docker setup
**File to Fix:**
- `docker/init-db/01-create-databases.sql`
---
### 5. **NO CI/CD QUALITY GATES** 🔴
**Severity:** HIGH
**Impact:** Broken code can be merged to main
**Risk:** Production outages, customer impact
**Current State:**
- ❌ No PR validation workflow (disabled - `.bak` file)
- ❌ No lint checks in CI
- ❌ No type-check in CI
- ❌ No test validation in CI
- ✅ Only Docker builds run (minimal validation)
**IMMEDIATE ACTIONS REQUIRED:**
1. ✅ Restore `.github/workflows/ci-pull-request.yml`
2. ✅ Add `pnpm lint` to PR checks
3. ✅ Add `pnpm type-check` to PR checks
4. ✅ Add `pnpm test` to PR checks (when tests exist)
5. ✅ Add coverage reporting (Codecov)
---
## 📊 DETAILED FINDINGS BY DIMENSION
### DOCUMENTATION (70/100 - Good)
**Strengths:**
- ✅ Excellent root `CLAUDE.md` structure
- ✅ Comprehensive authentication documentation
- ✅ Detailed guidelines in `.claude/guidelines/`
- ✅ Well-documented centralized env var system
**Issues:**
- 🟡 35% of projects missing from root docs (6/17 documented)
- 🟡 3 major projects lack CLAUDE.md (manadeck, picture, quote)
- 🟡 5 projects in both `apps/` and `apps-archived/` (confusion)
- 🟡 34 shared packages exist, only 10 documented
- 🟡 Backend port numbers incomplete (5/12 documented)
**Detailed Report:** `.claude/audit/documentation-audit-2025-12-07.md`
---
### CODE QUALITY (70/100 - Good)
**Strengths:**
- ✅ Full Svelte 5 runes adoption (0 old syntax files!)
- ✅ Result type error handling (48 service methods)
- ✅ Consistent auth integration (80 guard usages)
- ✅ Well-organized shared packages (37 packages)
**Issues:**
- 🔴 TypeScript `any` usage: 124 occurrences (type safety compromised)
- 🟡 Throwing exceptions in services: 27 violations (should use Result types)
- 🟡 Console statements in production: 13 occurrences
- 🟡 Default exports: 15 files (should use named exports)
**Code Duplication Opportunities:**
- Error handling pattern (~200 lines could be shared)
- API client boilerplate (~500 lines duplicate)
- Loading/error/empty states (30+ components)
**Technical Debt Score:** 6.5/10 (Moderate-High)
**Detailed Report:** See Coder Agent output above
---
### ARCHITECTURE & INFRASTRUCTURE (90/100 - Excellent)
**Strengths:**
- ✅ Centralized auth with Better Auth (EdDSA, JWKS)
- ✅ S3-compatible storage abstraction (MinIO → Hetzner)
- ✅ Clean monorepo structure (pnpm + turborepo)
- ✅ Automated environment generation
- ✅ Docker-based local development
**Issues:**
- 🔴 Auth service is single point of failure (no HA)
- 🟡 JWT validation requires network call (should use JWKS locally)
- 🟡 No database backup strategy documented
- 🟡 Inconsistent database connection patterns (3 different approaches)
- 🟡 Only 3/12 backends have Docker images
**Scalability Concerns:**
- Single PostgreSQL instance for 17+ databases
- No CDN for static assets
- No rate limiting in apps
- No real-time/WebSocket architecture
**Detailed Report:** See Analyst Agent output above
---
### TESTING (10/100 - Critical Failure)
**Strengths:**
- ✅ Excellent test patterns in mana-core-auth (80% coverage, mock factories, integration tests)
- ✅ Jest/Vitest infrastructure configured
- ✅ Playwright config exists
**Issues:**
- 🔴 Backend coverage: 8% (1/12 tested)
- 🔴 Mobile coverage: 0% (0/7 tested)
- 🔴 Web coverage: 0% (0/7 tested)
- 🔴 Shared packages: 0% (0/37 tested)
- 🔴 E2E tests: 0 scenarios
**Critical Gaps:**
- Authentication integration tests (security risk!)
- Credit consumption tests (billing risk!)
- Storage operation tests (data loss risk!)
- API endpoint tests (stability risk!)
**Detailed Report:** See Tester Agent output above
---
## 🎯 CONSENSUS RECOMMENDATIONS
The hive mind has achieved consensus on the following prioritized action plan:
### WEEK 1: SECURITY & CRITICAL FIXES
| Priority | Action | Owner | Effort |
|----------|--------|-------|--------|
| 1 | Revoke exposed API keys | DevOps | 2h |
| 2 | Implement secrets management | DevOps | 8h |
| 3 | Fix database initialization script | Backend | 2h |
| 4 | Enable CI PR validation | DevOps | 4h |
| 5 | Remove pre-commit global type-check | DevOps | 1h |
**Total Effort:** 17 hours
**Success Criteria:** No secrets in git, PR validation active, local dev setup works
---
### WEEK 2-4: TESTING FOUNDATION
| Priority | Action | Owner | Effort |
|----------|--------|-------|--------|
| 6 | Test shared-nestjs-auth package | Backend | 16h |
| 7 | Test shared-storage package | Backend | 12h |
| 8 | Test shared-errors package | Backend | 8h |
| 9 | Test chat backend (auth + credits + API) | Backend | 40h |
| 10 | Test picture backend | Backend | 32h |
| 11 | Test zitare backend | Backend | 24h |
**Total Effort:** 132 hours
**Success Criteria:** Critical packages at 80%+ coverage, top 3 backends at 70%+
---
### MONTH 2: INFRASTRUCTURE & AUTOMATION
| Priority | Action | Owner | Effort |
|----------|--------|-------|--------|
| 12 | Add Docker images for all backends | DevOps | 40h |
| 13 | Implement JWKS-based JWT validation | Backend | 16h |
| 14 | Set up HA for mana-core-auth | DevOps | 24h |
| 15 | Configure Turborepo remote caching | DevOps | 8h |
| 16 | Add database backup automation | DevOps | 12h |
| 17 | Add deployment monitoring | DevOps | 16h |
**Total Effort:** 116 hours
**Success Criteria:** All services deployable, HA auth, monitoring active
---
### MONTH 3: COVERAGE EXPANSION
| Priority | Action | Owner | Effort |
|----------|--------|-------|--------|
| 18 | Test remaining backends | Backend | 80h |
| 19 | Test mobile apps (chat, picture, manadeck) | Mobile | 180h |
| 20 | Test web apps (chat, picture) | Frontend | 80h |
| 21 | Create E2E test suite (10 scenarios) | QA | 60h |
| 22 | Update documentation (all missing) | Tech Writer | 24h |
**Total Effort:** 424 hours
**Success Criteria:** 70%+ coverage across all active projects
---
## 📈 SUCCESS METRICS & TRACKING
### Coverage Targets
| Metric | Current | 1 Month | 3 Months | 6 Months |
|--------|---------|---------|----------|----------|
| **Security Score** | 50/100 | 80/100 | 90/100 | 95/100 |
| **Test Coverage** | <1% | 40% | 70% | 80% |
| **CI/CD Automation** | 20% | 70% | 90% | 95% |
| **Documentation Coverage** | 70% | 85% | 95% | 100% |
| **Build Performance** | Poor | Good | Excellent | Excellent |
### Key Performance Indicators (KPIs)
- **Mean Time to Deploy (MTTD):** Target <15 minutes
- **Test Execution Time:** Target <5 minutes (unit), <15 minutes (full)
- **CI Success Rate:** Target >99%
- **Code Coverage:** Target 80% for new code
- **Documentation Completeness:** Target 100% of active projects
---
## 🗺️ COMPREHENSIVE IMPROVEMENT ROADMAP
### Phase 1: Stabilization (Month 1)
**Focus:** Security, testing foundation, CI/CD
**Deliverables:**
- ✅ No secrets in git
- ✅ Shared packages at 80%+ coverage
- ✅ Top 3 backends at 70%+ coverage
- ✅ PR validation active
- ✅ Database setup automated
**Exit Criteria:** Can deploy with confidence, critical paths tested
---
### Phase 2: Expansion (Months 2-3)
**Focus:** Full test coverage, infrastructure hardening
**Deliverables:**
- ✅ All backends tested (70%+)
- ✅ Mobile apps tested (60%+)
- ✅ Web apps tested (60%+)
- ✅ E2E test suite (10 scenarios)
- ✅ HA authentication
- ✅ All services deployable
**Exit Criteria:** Production-ready infrastructure, comprehensive testing
---
### Phase 3: Optimization (Months 4-6)
**Focus:** Performance, monitoring, scalability
**Deliverables:**
- ✅ Remote caching enabled
- ✅ CDN for static assets
- ✅ Rate limiting everywhere
- ✅ APM/logging/metrics
- ✅ Disaster recovery tested
- ✅ 80%+ coverage maintained
**Exit Criteria:** Scalable, observable, resilient system
---
## 📁 AUDIT DELIVERABLES
All detailed reports and checklists are available in `.claude/audit/`:
1. **README.md** - Navigation guide
2. **AUDIT_SUMMARY.md** - Quick reference (from Researcher)
3. **documentation-audit-2025-12-07.md** - Full documentation findings
4. **FIXES_CHECKLIST.md** - Step-by-step implementation guide
5. **HIVE_MIND_EXECUTIVE_SUMMARY.md** - This document
6. **CODE_QUALITY_REPORT.md** - Detailed code analysis (from Coder)
7. **ARCHITECTURE_REPORT.md** - Infrastructure analysis (from Analyst)
8. **TESTING_REPORT.md** - Test coverage assessment (from Tester)
---
## 🎓 LESSONS LEARNED
### What's Working Well
1. **Architectural Vision** - Centralized auth, shared packages, monorepo structure
2. **Developer Experience** - Automated env generation, Docker setup, clear guidelines
3. **Code Patterns** - Svelte 5 runes, Result types, auth integration
4. **Documentation Quality** - Where it exists, it's excellent (mana-core-auth, root CLAUDE.md)
### What Needs Improvement
1. **Quality Assurance** - Testing is virtually absent
2. **Security Practices** - Secrets management, vulnerability scanning
3. **Operational Readiness** - Deployment automation, monitoring, backups
4. **Documentation Coverage** - Many projects undocumented
### Strategic Insights
The monorepo demonstrates **excellent engineering judgment in architecture** but **insufficient investment in quality assurance**. This pattern is common in early-stage products prioritizing features over robustness. The foundation is solid - the missing piece is **automated validation** to maintain quality at scale.
**Key Recommendation:** Shift focus from feature development to **testing infrastructure** for the next 1-3 months. The ROI will be massive: faster feature development, fewer production bugs, and confident deployments.
---
## 🚀 NEXT STEPS
### Immediate Actions (Today)
1. ✅ Review this executive summary
2. ✅ Prioritize Week 1 critical fixes
3. ✅ Assign owners to tasks
4. ✅ Set up project tracking (GitHub Projects/Jira)
### Week 1 Kickoff
1. ✅ Security sprint: Revoke keys, implement secrets management
2. ✅ Database sprint: Fix initialization, test fresh setup
3. ✅ CI/CD sprint: Enable PR validation, remove slow type-check
### Month 1 Planning
1. ✅ Allocate resources for testing foundation (132 hours)
2. ✅ Set up coverage tracking (Codecov)
3. ✅ Weekly progress reviews
### Quarterly Review
1. ✅ Assess progress against roadmap
2. ✅ Adjust priorities based on learnings
3. ✅ Celebrate wins (coverage milestones!)
---
## 🤝 HIVE MIND CONSENSUS
All four specialized agents (Researcher, Coder, Analyst, Tester) have reached consensus on the following assessment:
**The manacore-monorepo is a well-architected system with critical gaps in quality assurance and operational readiness. With focused effort over the next 3 months on testing, security, and CI/CD, it can become a production-grade platform supporting 18+ applications.**
**Consensus Vote:** 4/4 agents agree
**Confidence Level:** High (based on comprehensive analysis)
**Recommended Action:** Proceed with Week 1 critical fixes immediately
---
**End of Executive Summary**
*Generated by Hive Mind Swarm: swarm-1765095736318-q124en9du*
*Queen Coordinator: Strategic Analysis Agent*
*Worker Agents: Researcher, Coder, Analyst, Tester*
*Audit Date: 2025-12-07*

155
.claude/audit/README.md
View file

@ -1,155 +0,0 @@
# 🧠 Hive Mind Collective Intelligence Audit
## ManaCore Monorepo Comprehensive Analysis
**Audit Date:** 2025-12-07
**Swarm ID:** swarm-1765095736318-q124en9du
**Status:** ✅ Complete
---
## 📄 Core Documents
### [HIVE_MIND_EXECUTIVE_SUMMARY.md](./HIVE_MIND_EXECUTIVE_SUMMARY.md) ⭐ START HERE
**Overall assessment** - High-level overview from all four agents
- Overall health score: 60/100 (C grade)
- Top 5 critical findings
- Consensus recommendations
- 3-month roadmap
### [ACTION_PLAN_WEEK_1.md](./ACTION_PLAN_WEEK_1.md) 🚨 URGENT
**Immediate actions** - What to do RIGHT NOW
- 5 critical tasks (17 hours total)
- Security fixes (API keys exposed!)
- Database initialization
- CI/CD activation
- Pre-commit optimization
### [AUDIT_SUMMARY.md](./AUDIT_SUMMARY.md)
**Documentation quick reference** - From Researcher Agent
- Key statistics
- Top 3 critical issues
- Quick action items
- Priority matrix
### [documentation-audit-2025-12-07.md](./documentation-audit-2025-12-07.md)
**Full documentation audit** - Complete analysis from Researcher Agent
- Executive summary
- 12 documented findings with examples
- File references and line numbers
- Appendices with complete data
- Recommendations by priority
### [FIXES_CHECKLIST.md](./FIXES_CHECKLIST.md)
**Implementation guide** - Step-by-step fixes for documentation
- Phased approach (4 phases)
- Checkbox format for progress tracking
- Specific file paths and line numbers
- Verification checklist
## 🎯 Quick Start
1. **Read the summary:** [AUDIT_SUMMARY.md](./AUDIT_SUMMARY.md) (5 minutes)
2. **Review critical issues:** Top 3 in summary
3. **Start fixing:** Use [FIXES_CHECKLIST.md](./FIXES_CHECKLIST.md)
4. **Deep dive:** Reference [full report](./documentation-audit-2025-12-07.md) as needed
## 📊 Key Findings Summary
| Metric | Status |
|--------|--------|
| **Overall Documentation Quality** | 7/10 |
| **Projects with Docs** | 11/17 (65%) |
| **Critical Issues** | 3 |
| **High Priority Issues** | 4 |
| **Medium Priority Issues** | 3 |
| **Low Priority Issues** | 2 |
## 🚨 Top 3 Critical Issues
1. **Active vs Archived Confusion** - 5 projects in both `apps/` and `apps-archived/`
2. **Missing Major Documentation** - manadeck, picture have no CLAUDE.md
3. **Incomplete Root Docs** - Only 6/17 active projects documented
## ✅ What to Fix First
**Week 1 Priority:**
1. Resolve duplicate projects (apps/ vs apps-archived/)
2. Create CLAUDE.md for manadeck and picture
3. Update root CLAUDE.md with all 17 active projects
4. Clean up invalid commands in package.json
## 📈 Success Metrics
**Target:**
- ✅ 100% active projects in root docs
- ✅ 100% active projects have CLAUDE.md
- ✅ All backend ports documented
- ✅ Zero duplicate projects
**Current:**
- ⚠️ 35% in root docs (6/17)
- ⚠️ 65% have CLAUDE.md (11/17)
- ⚠️ 42% backends documented (5/12)
- ❌ 5 duplicate projects
## 🔍 Audit Methodology
This audit was conducted by:
1. Scanning all CLAUDE.md files across the monorepo
2. Comparing documented structure vs actual filesystem
3. Verifying package.json commands
4. Checking consistency across documentation
5. Identifying gaps and inconsistencies
6. Prioritizing findings by impact
## 📝 Contributing to Fixes
When fixing documentation issues:
1. ✅ **Follow the checklist** - Use FIXES_CHECKLIST.md
2. ✅ **Update this README** - Mark issues as resolved
3. ✅ **Cross-reference** - Note which fixes address which findings
4. ✅ **Validate** - Test commands and verify accuracy
5. ✅ **Commit properly** - Reference audit findings in commits
Example commit:
```
docs: create manadeck CLAUDE.md
Addresses audit finding #2 (Missing Major Documentation)
See: .claude/audit/FIXES_CHECKLIST.md Phase 1
```
## 📅 Timeline
- **Audit Completed:** 2025-12-07
- **Phase 1 Target:** Week 1 (Critical fixes)
- **Phase 2 Target:** Week 2 (High priority)
- **Phase 3 Target:** Weeks 3-4 (Medium priority)
- **Phase 4 Target:** Future (Low priority)
## 🔗 Related Documentation
- [Root CLAUDE.md](../../CLAUDE.md) - Main project documentation
- [Guidelines Directory](../) - Code and architecture guidelines
- [Project Overview](../../docs/PROJECT_OVERVIEW.md) - High-level overview
- [Environment Variables](../../docs/ENVIRONMENT_VARIABLES.md) - Env setup
## 💡 Tips
- **For Quick Fixes:** Use AUDIT_SUMMARY.md for the immediate action items
- **For Deep Work:** Read the full report to understand context
- **For Tracking:** Check off items in FIXES_CHECKLIST.md as you complete them
- **For Context:** Reference the full report for examples and rationale
## 📧 Questions?
If you have questions about:
- **Why something is an issue:** See the full report
- **How to fix it:** See FIXES_CHECKLIST.md
- **What to prioritize:** See AUDIT_SUMMARY.md priority matrix
---
**Last Updated:** 2025-12-07
**Next Review:** After Phase 1 completion

583
.claude/audit/documentation-audit-2025-12-07.md
View file

@ -1,583 +0,0 @@
# Documentation Audit Report
**Date:** 2025-12-07
**Auditor:** Claude Code (Swarm Research Agent)
**Scope:** Complete documentation review of manacore-monorepo
---
## Executive Summary
This audit reviewed all CLAUDE.md files, guideline documents, and cross-referenced them with actual codebase structure. The monorepo has **17 active projects** in `apps/`, **5 game projects** in `games/`, **16 archived projects** in `apps-archived/`, and **1 service** (`mana-core-auth`).
**Overall Documentation Quality:** 7/10
- ✅ Root CLAUDE.md is comprehensive and well-structured
- ✅ Most active projects have detailed CLAUDE.md files
- ⚠️ Several projects missing from root documentation
- ⚠️ Some inconsistencies between docs and actual structure
- ❌ Several projects completely undocumented
---
## Critical Findings (Priority: HIGH)
### 1. **Missing Project Documentation in Root CLAUDE.md**
The root `/CLAUDE.md` only documents 6 projects, but there are **17 active projects** in `apps/`:
**Documented (6):**
- manacore
- manadeck
- picture
- chat
- zitare
- contacts
**Missing from Documentation (11):**
- **calendar** - Full calendar app (backend, web, landing) - Port 3014
- **clock** - World clock/timer app (backend, web, landing) - Port 3017
- **context** - AI document management (mobile only)
- **todo** - Task management app (backend, web, landing) - Port 3018
- **maerchenzauber** - AI story generation (backend, mobile) - ACTIVE in `apps/` but also listed as archived
- **memoro** - Voice memo app (mobile only) - ACTIVE in `apps/` but also listed as archived
- **nutriphi** - Nutrition tracking (backend, mobile) - ACTIVE in `apps/` but also listed as archived
- **quote** - Quote app (backend, web, mobile)
- **reader** - Reading app (mobile only) - ACTIVE in `apps/` but also listed as archived
- **wisekeep** - AI wisdom extraction (backend, mobile) - ACTIVE in `apps/` but also listed as archived
- **finance** - Finance app (documented in archived but exists in apps-archived)
- **moodlit** - Mood tracking (documented in archived but exists in apps-archived)
**Impact:** Developers/AI working on these projects have no guidance in the main documentation.
**Recommendation:** Add a comprehensive project table to root CLAUDE.md that lists ALL active projects with their status, apps (backend/web/mobile/landing), and ports.
---
### 2. **Projects Listed as "Archived" But Actually Active**
**CRITICAL CONFUSION:** The root CLAUDE.md lists these as archived in `apps-archived/`:
- maerchenzauber
- memoro
- wisekeep
- reader
- nutriphi
**BUT:** These projects actually exist in `apps/` (active workspace):
- `/apps/maerchenzauber/` ✅ EXISTS (backend + mobile)
- `/apps/memoro/` ✅ EXISTS (mobile only)
- `/apps/wisekeep/` ✅ EXISTS (backend + mobile)
- `/apps/reader/` ✅ EXISTS (mobile only)
- `/apps/nutriphi/` ✅ EXISTS (backend + mobile)
**Also in apps-archived/:**
- `/apps-archived/maerchenzauber/` ✅ EXISTS
- `/apps-archived/memoro/` ✅ EXISTS
- `/apps-archived/wisekeep/` ✅ EXISTS
- `/apps-archived/reader/` ✅ EXISTS
- `/apps-archived/nutriphi/` ✅ EXISTS
**Impact:** This creates severe confusion. It appears these projects were copied to `apps/` from `apps-archived/` but the documentation was not updated. Developers don't know if these are active or archived.
**Recommendation:**
1. Determine which version is canonical (apps/ or apps-archived/)
2. Remove duplicates
3. Update documentation to reflect actual status
4. If both versions should exist, explain why in documentation
---
### 3. **Missing Project-Level CLAUDE.md Files**
**Projects WITH CLAUDE.md (11):**
- ✅ calendar (detailed, German)
- ✅ chat (comprehensive)
- ✅ clock (detailed, German)
- ✅ contacts (comprehensive)
- ✅ context (concise but complete)
- ✅ manacore (exists, need to verify)
- ✅ todo (detailed, German)
- ✅ zitare (comprehensive)
- ✅ mana-core-auth (service)
- ✅ Several archived projects (maerchenzauber, reader, uload)
- ✅ Game projects (figgos, mana-games, voxelava, worldream)
**Projects MISSING CLAUDE.md (6+):**
- ❌ **manadeck** - Major project with backend/web/mobile/landing
- ❌ **picture** - AI image generation project
- ❌ **quote** - Quote management app
- ❌ **maerchenzauber** (active version in apps/)
- ❌ **memoro** (active version in apps/)
- ❌ **nutriphi** (active version in apps/)
- ❌ **wisekeep** (active version in apps/)
- ❌ **reader** (active version in apps/)
- ❌ All projects in `apps-archived/` that don't have CLAUDE.md
**Impact:** No project-specific guidance for important projects like manadeck and picture, which are prominently featured in root docs.
**Recommendation:** Create CLAUDE.md files for all active projects, especially manadeck and picture.
---
## Medium Priority Findings
### 4. **Inconsistent Landing Page Documentation**
**Root CLAUDE.md** lists landing pages for:
- Chat ✅
- Picture ✅
- ManaCore ✅
- ManaDeck ✅
- Zitare ✅
**BUT actual landing pages exist for (7 total):**
- ✅ chat
- ✅ picture
- ✅ manacore
- ✅ manadeck
- ✅ zitare
- ✅ **calendar** (NOT documented in root)
- ✅ **clock** (NOT documented in root)
**Deploy scripts exist for (10):**
```json
"deploy:landing:chat"
"deploy:landing:picture"
"deploy:landing:manacore"
"deploy:landing:manadeck"
"deploy:landing:zitare"
"deploy:landing:presi" // Landing doesn't exist
"deploy:landing:clock"
"deploy:landing:mail" // Landing doesn't exist
"deploy:landing:moodlit" // Landing doesn't exist
"deploy:landing:all"
```
**Impact:** Documentation doesn't reflect which projects actually have landing pages vs which have deploy scripts.
**Recommendation:**
1. Remove deploy scripts for non-existent landing pages (presi, mail, moodlit)
2. Document calendar and clock landing pages in root CLAUDE.md
3. Update "Landing Pages" section to be accurate
---
### 5. **Backend Port Documentation Inconsistencies**
**Root CLAUDE.md** documents these backend ports:
- Chat: 3002 ✅
- Picture: 3006 ✅
- Zitare: 3007 ✅
- Presi: 3008 (⚠️ presi backend doesn't exist in apps/)
- ManaDeck: 3009 ✅
**Missing from root docs:**
- **Calendar backend:** Port 3014 (from calendar/CLAUDE.md)
- **Contacts backend:** Port 3015 (from contacts/CLAUDE.md)
- **Clock backend:** Port 3017 (from clock/CLAUDE.md)
- **Todo backend:** Port 3018 (from todo/CLAUDE.md)
- **mana-core-auth:** Port 3001 (documented in auth section)
**Recommendation:** Create a complete backend port reference table in root CLAUDE.md.
---
### 6. **Games Projects Not Documented**
**Games directory exists with 5 projects:**
- figgos (with CLAUDE.md ✅)
- mana-games (with CLAUDE.md ✅)
- voxelava
- whopixels
- worldream (with CLAUDE.md ✅)
**Root CLAUDE.md mentions:**
```
├── games/ # Game projects
│ └── {game-name}/ # Individual games
```
But provides NO details about which games exist or their status.
**Recommendation:** Add a "Game Projects" section listing all games with brief descriptions.
---
### 7. **Shared Packages Documentation Gaps**
**Root CLAUDE.md lists 10 shared packages:**
- @manacore/shared-nestjs-auth ✅
- @mana-core/nestjs-integration ✅
- @manacore/shared-auth ✅
- @manacore/shared-storage ✅
- @manacore/shared-supabase ✅
- @manacore/shared-types ✅
- @manacore/shared-utils ✅
- @manacore/shared-ui ✅
- @manacore/shared-theme ✅
- @manacore/shared-i18n ✅
**Actual packages/ directory has 34 packages:**
```
eslint-config
mana-core-nestjs-integration
manadeck-database
news-database
nutriphi-database
shared-api-client
shared-auth
shared-auth-stores
shared-auth-ui
shared-branding
shared-config
shared-credit-service
shared-errors
shared-feedback-service
shared-feedback-types
shared-feedback-ui
shared-i18n
shared-icons
shared-landing-ui
shared-nestjs-auth
shared-profile-ui
shared-storage
shared-stores
shared-subscription-types
shared-subscription-ui
shared-supabase
shared-tailwind
shared-theme
shared-theme-ui
shared-types
shared-ui
shared-utils
shared-vite-config
test-config
uload-database
```
**Missing from documentation:**
- @manacore/shared-errors
- @manacore/shared-api-client
- @manacore/shared-auth-stores
- @manacore/shared-auth-ui
- @manacore/shared-branding
- @manacore/shared-config
- @manacore/shared-credit-service
- @manacore/shared-feedback-service
- @manacore/shared-feedback-types
- @manacore/shared-feedback-ui
- @manacore/shared-icons
- @manacore/shared-landing-ui
- @manacore/shared-profile-ui
- @manacore/shared-stores
- @manacore/shared-subscription-types
- @manacore/shared-subscription-ui
- @manacore/shared-tailwind
- @manacore/shared-theme-ui
- @manacore/shared-vite-config
- @manacore/test-config
- @manacore/eslint-config
- Project-specific DB packages (manadeck-database, news-database, nutriphi-database, uload-database)
**Recommendation:** Add a complete packages reference or link to a dedicated packages documentation file.
---
## Low Priority Findings
### 8. **Development Commands Missing for Some Projects**
**Root CLAUDE.md** provides dev commands for:
- manacore:dev ✅
- manadeck:dev ✅
- picture:dev ✅
- chat:dev ✅
- zitare:dev ✅
- presi:dev ⚠️ (presi doesn't exist in apps/, only in apps-archived/)
- contacts:dev ✅
- mail:dev ⚠️ (mail exists in apps-archived/, not apps/)
**Missing commands for active projects:**
- calendar:dev (exists in package.json ✅)
- clock:dev (exists in package.json ✅)
- todo:dev (exists in package.json ✅)
- moodlit:dev (exists in package.json ✅)
- finance:dev (exists in package.json ✅)
- context:dev (exists in package.json ✅)
- worldream:dev (exists in package.json ✅)
- figgos:dev (exists in package.json ✅)
- mana-games:dev (exists in package.json ✅)
- voxel-lava:dev (exists in package.json ✅)
**Recommendation:** Update command examples to include all active projects or use a pattern like "pnpm {project}:dev".
---
### 9. **Environment Variables Documentation Inconsistencies**
**Root CLAUDE.md** references:
- `/docs/ENVIRONMENT_VARIABLES.md` ✅ (file exists and is comprehensive)
**But ENVIRONMENT_VARIABLES.md documents these projects:**
- Mana Core Auth ✅
- Chat ✅
- Maerchenzauber ✅
- Memoro ✅
- Manacore ✅
- Manadeck ✅
**Missing from ENVIRONMENT_VARIABLES.md:**
- calendar
- clock
- contacts
- todo
- zitare
- picture
- All games
- All other active projects
**Recommendation:** Update docs/ENVIRONMENT_VARIABLES.md to include all active projects or clearly state it's only for select projects.
---
### 10. **Archived Projects Documentation Confusion**
**Root CLAUDE.md** lists 12 archived projects:
- bauntown ✅ (in apps-archived/)
- maerchenzauber ⚠️ (in BOTH apps/ and apps-archived/)
- memoro ⚠️ (in BOTH apps/ and apps-archived/)
- news ✅ (in apps-archived/)
- nutriphi ⚠️ (in BOTH apps/ and apps-archived/)
- reader ⚠️ (in BOTH apps/ and apps-archived/)
- uload ✅ (in apps-archived/)
- wisekeep ⚠️ (in BOTH apps/ and apps-archived/)
- techbase ✅ (in apps-archived/)
- inventory ✅ (in apps-archived/)
- presi ✅ (in apps-archived/)
- storage ✅ (in apps-archived/)
**Actually in apps-archived/ (16):**
- bauntown ✅
- finance ❌ (not listed as archived)
- inventory ✅
- maerchenzauber ⚠️
- mail ❌ (not listed as archived)
- memoro ⚠️
- moodlit ❌ (not listed as archived)
- news ✅
- nutriphi ⚠️
- presi ✅
- reader ⚠️
- storage ✅
- techbase ✅
- uload ✅
- wisekeep ⚠️
**Missing from archived list:**
- finance
- mail
- moodlit
**Recommendation:** Create accurate archived projects list and remove duplicates between apps/ and apps-archived/.
---
### 11. **S3 Buckets Documentation**
**Root CLAUDE.md** lists these pre-configured buckets:
- picture-storage (Picture)
- chat-storage (Chat)
- manadeck-storage (ManaDeck)
- nutriphi-storage (NutriPhi)
- presi-storage (Presi)
- calendar-storage (Calendar)
- contacts-storage (Contacts)
- storage-storage (Storage)
**Issues:**
- "storage-storage" is confusing naming
- Missing buckets for: clock, todo, zitare, etc.
- NutriPhi, Presi, Storage are archived - should they have buckets?
**Recommendation:** Verify which buckets actually exist in MinIO/Hetzner and update docs accordingly.
---
### 12. **Technology Stack Version Ranges Too Wide**
Root CLAUDE.md states:
- "React Native 0.76-0.81 + Expo SDK 52-54"
- "NestJS 10-11"
**Issue:** Version ranges should be more specific. Different projects may use different versions, causing confusion.
**Recommendation:** Either:
1. Specify exact versions used across monorepo
2. Link to a version compatibility matrix
3. State "varies by project, see project CLAUDE.md"
---
## Positive Findings
### What's Working Well ✅
1. **Root CLAUDE.md Structure** - Very well organized with clear sections
2. **Authentication Documentation** - Excellent detail on mana-core-auth integration
3. **Turborepo Configuration** - Critical recursive call warning is prominently documented
4. **Environment Setup** - Centralized .env.development system is well explained
5. **Shared Packages Philosophy** - Good explanation of import patterns
6. **Code Quality Section** - Good forward-looking documentation of planned infrastructure
7. **Project-Level Docs** - Where they exist (calendar, clock, contacts, todo, zitare), they're comprehensive
8. **Svelte 5 Runes** - Clear examples of correct vs incorrect usage
9. **Guidelines Directory** - Excellent `.claude/GUIDELINES.md` with links to detailed guides
10. **Landing Page Deployment** - Clear Cloudflare Pages workflow documented
---
## Recommendations by Priority
### Immediate Actions (This Week)
1. **Resolve Active vs Archived Confusion**
- Determine status of: maerchenzauber, memoro, wisekeep, reader, nutriphi
- Remove duplicates
- Update root CLAUDE.md
2. **Create Missing Project CLAUDE.md Files**
- manadeck
- picture
- All active projects without docs
3. **Update Root Projects Table**
- Add all 17 active projects
- Include: name, description, apps (backend/web/mobile/landing), port numbers
4. **Fix Landing Pages Section**
- Remove non-existent landing deploy scripts
- Add calendar, clock to landing pages list
### Short-term Actions (This Month)
5. **Backend Ports Reference Table**
- Complete table of all backends with ports in root CLAUDE.md
6. **Update Shared Packages List**
- Document all 34 packages or create dedicated packages.md
7. **Environment Variables Audit**
- Update docs/ENVIRONMENT_VARIABLES.md for all active projects
8. **Games Projects Section**
- Add games overview to root CLAUDE.md
### Long-term Improvements
9. **Version Compatibility Matrix**
- Document exact versions per project
10. **Automated Documentation Checks**
- Script to verify CLAUDE.md exists for all projects
- Script to check root docs match actual structure
11. **Documentation Generation**
- Auto-generate project list from filesystem
- Auto-generate port assignments from backend configs
---
## Statistics
| Metric | Count |
|--------|-------|
| **Active Projects (apps/)** | 17 |
| **Game Projects (games/)** | 5 |
| **Archived Projects (apps-archived/)** | 16 |
| **Services (services/)** | 1 (mana-core-auth) |
| **Projects with CLAUDE.md** | ~11 active + several archived |
| **Projects without CLAUDE.md** | ~6 major projects |
| **Backends in active apps/** | 12 |
| **Documented backends in root** | 5 |
| **Landing pages (actual)** | 7 |
| **Landing pages (documented)** | 5 |
| **Deploy scripts for landing** | 10 |
| **Shared packages (actual)** | 34 |
| **Shared packages (documented)** | 10 |
---
## Appendix A: Complete Active Projects List
| Project | Backend | Web | Mobile | Landing | Port | Status |
|---------|---------|-----|--------|---------|------|--------|
| calendar | ✅ | ✅ | ❌ | ✅ | 3014 | Active, documented |
| chat | ✅ | ✅ | ✅ | ✅ | 3002 | Active, documented |
| clock | ✅ | ✅ | ❌ | ✅ | 3017 | Active, documented |
| contacts | ✅ | ✅ | ❌ | ❌ | 3015 | Active, documented |
| context | ❌ | ❌ | ✅ | ❌ | - | Active, documented |
| maerchenzauber | ✅ | ❌ | ✅ | ❌ | ? | ⚠️ Duplicate in archived |
| manacore | ❌ | ✅ | ✅ | ✅ | - | Active, documented |
| manadeck | ✅ | ✅ | ✅ | ✅ | 3009 | Active, NO docs |
| memoro | ❌ | ❌ | ✅ | ❌ | - | ⚠️ Duplicate in archived |
| nutriphi | ✅ | ❌ | ✅ | ❌ | ? | ⚠️ Duplicate in archived |
| picture | ✅ | ✅ | ✅ | ✅ | 3006 | Active, NO docs |
| quote | ✅ | ✅ | ✅ | ❌ | ? | Active, NO docs |
| reader | ❌ | ❌ | ✅ | ❌ | - | ⚠️ Duplicate in archived |
| todo | ✅ | ✅ | ❌ | ❌ | 3018 | Active, documented |
| wisekeep | ✅ | ❌ | ✅ | ❌ | ? | ⚠️ Duplicate in archived |
| zitare | ✅ | ✅ | ✅ | ✅ | 3007 | Active, documented |
---
## Appendix B: Documentation Coverage Matrix
| Document | Exists | Accuracy | Completeness | Notes |
|----------|--------|----------|--------------|-------|
| `/CLAUDE.md` | ✅ | 7/10 | 6/10 | Missing many projects |
| `.claude/GUIDELINES.md` | ✅ | 9/10 | 9/10 | Excellent |
| `.claude/guidelines/*.md` | ✅ | 9/10 | 9/10 | Comprehensive |
| `docs/ENVIRONMENT_VARIABLES.md` | ✅ | 8/10 | 5/10 | Incomplete project coverage |
| `apps/calendar/CLAUDE.md` | ✅ | 10/10 | 10/10 | Excellent, German |
| `apps/chat/CLAUDE.md` | ✅ | 9/10 | 9/10 | Comprehensive |
| `apps/clock/CLAUDE.md` | ✅ | 10/10 | 10/10 | Excellent, German |
| `apps/contacts/CLAUDE.md` | ✅ | 9/10 | 9/10 | Comprehensive |
| `apps/context/CLAUDE.md` | ✅ | 8/10 | 8/10 | Concise but complete |
| `apps/manadeck/CLAUDE.md` | ❌ | - | - | **MISSING** |
| `apps/manacore/CLAUDE.md` | ✅ | ? | ? | Not reviewed in detail |
| `apps/picture/CLAUDE.md` | ❌ | - | - | **MISSING** |
| `apps/todo/CLAUDE.md` | ✅ | 10/10 | 10/10 | Excellent, German |
| `apps/zitare/CLAUDE.md` | ✅ | 9/10 | 9/10 | Comprehensive |
| `services/mana-core-auth/CLAUDE.md` | ✅ | ? | ? | Not reviewed in detail |
---
## Appendix C: Recommended Actions Checklist
### Critical (Do First)
- [ ] Resolve maerchenzauber, memoro, wisekeep, reader, nutriphi duplicate status
- [ ] Create manadeck/CLAUDE.md
- [ ] Create picture/CLAUDE.md
- [ ] Update root CLAUDE.md projects table with all 17 active projects
- [ ] Remove presi:dev and mail:dev from root commands (they're archived)
- [ ] Add calendar, clock, todo to root CLAUDE.md
### High Priority
- [ ] Create backend ports reference table in root CLAUDE.md
- [ ] Fix landing pages documentation (remove presi, mail, moodlit deploy scripts)
- [ ] Add games section to root CLAUDE.md
- [ ] Update archived projects list to match apps-archived/
### Medium Priority
- [ ] Expand shared packages documentation
- [ ] Update docs/ENVIRONMENT_VARIABLES.md for all active projects
- [ ] Add CLAUDE.md for quote, and other undocumented active projects
- [ ] Document S3 buckets accurately
### Low Priority
- [ ] Create version compatibility matrix
- [ ] Verify all commands in package.json match documentation
- [ ] Add automated documentation validation scripts
- [ ] Consider auto-generating parts of documentation from filesystem
---
**End of Report**

487
.claude/plans/macbook-pro-server-setup.md
View file

@ -1,487 +0,0 @@
# Implementierungsplan: MacBook Pro M1 Max als zweiter Server
## Übersicht
**Ziel:** MacBook Pro M1 Max (64GB RAM) als AI/ML-Server einrichten, der parallel zum Mac Mini läuft.
**Zeitschätzung:** 4-6 Stunden für komplette Implementierung
---
## Phase 1: Hardware-Vorbereitung (30 Min)
### 1.1 MacBook Pro physisch vorbereiten
- [ ] Daten sichern (falls noch nicht geschehen)
- [ ] Vertikalen Laptop-Ständer besorgen (~25€)
- [ ] USB-C zu Ethernet Adapter besorgen (~30€)
- [ ] Stromleiste mit Überspannungsschutz (~30€)
- [ ] Position neben Mac Mini festlegen
### 1.2 Netzwerk-Konfiguration planen
```
Mac Mini: 192.168.x.10 (bestehend)
MacBook Pro: 192.168.x.11 (neu)
```
---
## Phase 2: macOS Setup auf MacBook Pro (1-2 Std)
### 2.1 Optionaler Clean Install
```bash
# Falls gewünscht: macOS neu installieren
# Recovery Mode: Cmd+R beim Start
# Festplattendienstprogramm → Löschen → APFS
# macOS neu installieren
```
### 2.2 Grundlegende Konfiguration
```bash
# Systemeinstellungen
# 1. Computername setzen
sudo scutil --set ComputerName "mana-server-ai"
sudo scutil --set HostName "mana-server-ai"
sudo scutil --set LocalHostName "mana-server-ai"
# 2. SSH aktivieren
# System Settings → General → Sharing → Remote Login → ON
# 3. Clamshell-Modus ermöglichen
# System Settings → Battery → Power Adapter:
# - "Prevent automatic sleeping when the display is off" → ON
# - "Wake for network access" → ON
# 4. Auto-Login (optional, für Server-Betrieb)
# System Settings → Users & Groups → Automatic Login
# 5. Autostart nach Stromausfall
sudo systemsetup -setrestartfreeze on
sudo systemsetup -setrestartpowerfailure on
```
### 2.3 Statische IP konfigurieren
```bash
# System Settings → Network → Ethernet → Details → TCP/IP
# Configure IPv4: Manually
# IP Address: 192.168.x.11
# Subnet Mask: 255.255.255.0
# Router: 192.168.x.1
# DNS: 1.1.1.1, 8.8.8.8
```
### 2.4 Development Tools installieren
```bash
# Xcode Command Line Tools
xcode-select --install
# Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Essentials
brew install git node pnpm python@3.11 cloudflared
# Docker Desktop
brew install --cask docker
# Nach Installation: Docker Desktop öffnen und starten
```
---
## Phase 3: Externe SSD einrichten (30 Min)
### 3.1 Verzeichnisstruktur erstellen
```bash
# SSD mounten (falls nicht automatisch)
# Erwarteter Mount-Punkt: /Volumes/ManaData-AI oder ähnlich
# Verzeichnisse erstellen
sudo mkdir -p /Volumes/ManaData-AI/{
ollama,
flux2,
stt-models,
tts-models,
postgres-replica,
backups
}
# Berechtigungen setzen
sudo chown -R $(whoami):staff /Volumes/ManaData-AI
```
### 3.2 Symlinks einrichten
```bash
# Ollama Modelle
ln -sf /Volumes/ManaData-AI/ollama ~/.ollama
# STT Modelle
ln -sf /Volumes/ManaData-AI/stt-models ~/stt-models
# TTS Modelle
ln -sf /Volumes/ManaData-AI/tts-models ~/tts-models
# FLUX.2 Modelle
ln -sf /Volumes/ManaData-AI/flux2 ~/flux2
```
---
## Phase 4: Cloudflare Tunnel einrichten (30 Min)
### 4.1 Neuen Tunnel erstellen
```bash
# Bei Cloudflare anmelden
cloudflared tunnel login
# Neuen Tunnel für MacBook Pro erstellen
cloudflared tunnel create mana-server-ai
# Tunnel-ID notieren (z.B. abc12345-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
export TUNNEL_ID="<tunnel-id-hier>"
# DNS-Routen erstellen
cloudflared tunnel route dns mana-server-ai mbp.mana.how
cloudflared tunnel route dns mana-server-ai llm.mana.how
cloudflared tunnel route dns mana-server-ai tts-v2.mana.how
cloudflared tunnel route dns mana-server-ai stt-v2.mana.how
cloudflared tunnel route dns mana-server-ai img.mana.how
```
### 4.2 Dateien zu erstellen
**Datei:** `cloudflared-config.macbookpro.yml`
```yaml
tunnel: <TUNNEL_ID>
credentials-file: /Users/mana/.cloudflared/<TUNNEL_ID>.json
ingress:
# SSH Access
- hostname: mbp.mana.how
service: ssh://localhost:22
# LLM Service (mana-llm mit Ollama)
- hostname: llm.mana.how
service: http://localhost:3025
originRequest:
connectTimeout: 300s
# TTS Service (Kokoro + F5)
- hostname: tts-v2.mana.how
service: http://localhost:3022
# STT Service (Whisper Large)
- hostname: stt-v2.mana.how
service: http://localhost:3021
# Image Generation (FLUX.2)
- hostname: img.mana.how
service: http://localhost:3023
# Catch-all
- service: http_status:404
```
---
## Phase 5: AI/ML Services installieren (2 Std)
### 5.1 Ollama mit großen Modellen
```bash
# Ollama installieren
brew install ollama
# Service starten
brew services start ollama
# Große Modelle laden (dauert je nach Verbindung)
ollama pull gemma3:27b # 16 GB - Hauptmodell
ollama pull llama3.1:70b # ~40 GB 4-bit quant (optional)
ollama pull codestral:22b # ~14 GB - Code
ollama pull deepseek-coder:33b # ~20 GB - Code (optional)
# Existierende kleinere Modelle auch laden für Kompatibilität
ollama pull gemma3:4b
ollama pull gemma3:12b
```
### 5.2 mana-tts mit F5-TTS
```bash
# Python Virtual Environment
python3.11 -m venv ~/venvs/mana-tts
source ~/venvs/mana-tts/bin/activate
# TTS Dependencies (inkl. F5-TTS für Voice Cloning)
pip install kokoro-onnx f5-tts torch torchaudio
pip install fastapi uvicorn python-multipart
# Modelle herunterladen
# (Details in services/mana-tts/setup.py oder setup-tts.sh)
```
**LaunchAgent erstellen:** `com.manacore.mana-tts.plist`
### 5.3 mana-stt mit Whisper Large
```bash
# Python Virtual Environment
python3.11 -m venv ~/venvs/mana-stt
source ~/venvs/mana-stt/bin/activate
# Whisper installieren
pip install openai-whisper faster-whisper
pip install fastapi uvicorn python-multipart
# Large-v3 Modell herunterladen (wird automatisch geladen)
# ~3 GB Download
```
**LaunchAgent erstellen:** `com.manacore.mana-stt.plist`
### 5.4 mana-image-gen mit FLUX.2
```bash
# Bestehende Setup-Skript verwenden (angepasst)
./scripts/mac-mini/setup-image-gen.sh
# Oder manuell:
cd ~/
git clone https://github.com/city96/flux2.c
cd flux2.c
make MPS=1 # Apple Metal Support
# Modell herunterladen (~16 GB)
# Details in services/mana-image-gen/
```
**LaunchAgent erstellen:** `com.manacore.image-gen.plist`
---
## Phase 6: Docker Services (Optional, für Replicas) (1 Std)
### 6.1 docker-compose.macbookpro.yml erstellen
Nur für:
- PostgreSQL Replica (Hot Standby)
- Redis Replica
- mana-llm Container
- Backup Worker
### 6.2 PostgreSQL Streaming Replication
**Auf Mac Mini (Primary):**
```bash
# postgresql.conf anpassen
wal_level = replica
max_wal_senders = 3
wal_keep_size = 64MB
# pg_hba.conf anpassen
host replication replicator 192.168.x.11/32 md5
```
**Auf MacBook Pro (Replica):**
```bash
# Base Backup vom Primary
pg_basebackup -h 192.168.x.10 -U replicator -D /Volumes/ManaData-AI/postgres-replica -P
# standby.signal erstellen
touch /Volumes/ManaData-AI/postgres-replica/standby.signal
# postgresql.auto.conf
primary_conninfo = 'host=192.168.x.10 port=5432 user=replicator password=xxx'
```
---
## Phase 7: Autostart & Health Checks (30 Min)
### 7.1 Scripts zu erstellen
```
scripts/macbook-pro/
├── setup-autostart.sh # LaunchAgents einrichten
├── startup.sh # Boot-Startup
├── health-check.sh # Service-Monitoring
├── status.sh # Übersicht
├── restart.sh # Services neustarten
└── stop.sh # Services stoppen
```
### 7.2 LaunchAgents zu erstellen
```
~/Library/LaunchAgents/
├── com.cloudflare.cloudflared.plist # Tunnel
├── com.manacore.mana-tts.plist # TTS Service
├── com.manacore.mana-stt.plist # STT Service
├── com.manacore.image-gen.plist # Image Gen
├── com.manacore.health-check.plist # Health Checks
└── homebrew.mxcl.ollama.plist # Ollama (auto von brew)
```
---
## Phase 8: Dokumentation & Testing (30 Min)
### 8.1 Dokumentation aktualisieren
**Dateien zu erstellen/aktualisieren:**
- `docs/MACBOOK_PRO_SERVER.md` - Neue Dokumentation
- `docs/MAC_MINI_SERVER.md` - Verweise auf MBP hinzufügen
- `docs/TWO_SERVER_ARCHITECTURE.md` - Architektur-Übersicht
- `CLAUDE.md` - SSH-Config für mbp hinzufügen
### 8.2 SSH-Config erweitern
```
# ~/.ssh/config
Host mana-server
HostName mac-mini.mana.how
User till
ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
Host mana-server-ai
HostName mbp.mana.how
User till
ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
```
### 8.3 Testing Checklist
- [ ] SSH zu MacBook Pro funktioniert: `ssh mana-server-ai`
- [ ] Ollama API erreichbar: `curl http://192.168.x.11:11434/api/version`
- [ ] TTS Service: `curl http://192.168.x.11:3022/health`
- [ ] STT Service: `curl http://192.168.x.11:3021/health`
- [ ] Image Gen: `curl http://192.168.x.11:3023/health`
- [ ] LLM Service: `curl https://llm.mana.how/health`
- [ ] PostgreSQL Replica synchronisiert
- [ ] Health Checks laufen alle 5 Min
- [ ] Notifications bei Fehlern
---
## Dateien die erstellt werden müssen
### Neue Dateien
| Datei | Beschreibung |
|-------|--------------|
| `docker-compose.macbookpro.yml` | Docker Compose für MBP (Replicas, mana-llm) |
| `cloudflared-config.macbookpro.yml` | Cloudflare Tunnel Config |
| `.env.macbookpro` | Environment Variables |
| `scripts/macbook-pro/setup-autostart.sh` | LaunchAgent Setup |
| `scripts/macbook-pro/startup.sh` | Boot Startup Script |
| `scripts/macbook-pro/health-check.sh` | Health Monitoring |
| `scripts/macbook-pro/status.sh` | Service Status |
| `scripts/macbook-pro/restart.sh` | Restart Services |
| `scripts/macbook-pro/stop.sh` | Stop Services |
| `scripts/macbook-pro/setup-ollama.sh` | Ollama Setup mit großen Modellen |
| `scripts/macbook-pro/setup-tts.sh` | TTS Setup mit F5 |
| `scripts/macbook-pro/setup-stt.sh` | STT Setup mit Whisper Large |
| `scripts/macbook-pro/backup-worker.sh` | Backup vom Mac Mini |
| `docker/postgres/replica-setup.sh` | PostgreSQL Replica Init |
| `docs/MACBOOK_PRO_SERVER.md` | Server Dokumentation |
| `docs/TWO_SERVER_ARCHITECTURE.md` | Architektur Übersicht |
### Zu aktualisierende Dateien
| Datei | Änderung |
|-------|----------|
| `CLAUDE.md` | SSH-Config für MBP |
| `docs/MAC_MINI_SERVER.md` | Verweise auf MBP |
| `.env.development` | MBP-spezifische Vars |
---
## Architektur nach Implementierung
```
┌─────────────────────────────────────┐
│ Cloudflare Tunnel │
│ *.mana.how → Mac Mini (Primary) │
│ llm/tts-v2/stt-v2/img.mana.how │
│ → MacBook Pro (AI/ML) │
└───────────────┬─────────────────────┘
│
┌─────────────────────┴─────────────────────┐
│ │
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ MAC MINI M4 (16GB) │ │ MACBOOK PRO M1 MAX (64GB) │
│ "Docker Orchestrator" │ │ "AI/ML Powerhouse" │
│ 192.168.x.10 │ │ 192.168.x.11 │
├─────────────────────────────┤ ├─────────────────────────────┤
│ │ │ │
│ PostgreSQL PRIMARY ─────────┼────────▶│ PostgreSQL REPLICA │
│ Redis PRIMARY ──────────────┼────────▶│ Redis REPLICA │
│ MinIO S3 │ │ │
│ │ │ Ollama (27B, 70B Modelle) │
│ mana-core-auth (Primary) │ │ mana-llm (large models) │
│ API Gateway │ │ │
│ mana-search + SearXNG │ │ mana-tts (Kokoro + F5) │
│ mana-media │ │ mana-stt (Whisper Large) │
│ │ │ mana-image-gen (2048x2048) │
│ Alle NestJS Backends │ │ │
│ Alle SvelteKit Frontends │ │ Backup-Worker │
│ Matrix Synapse + Bots │ │ │
│ Monitoring Stack │ │ │
│ n8n, Umami │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
ssh.mana.how mbp.mana.how
```
---
## Risiken & Mitigationen
| Risiko | Mitigation |
|--------|------------|
| MacBook-Akku bläht sich auf | Monatliche visuelle Prüfung; Al Dente App für Ladelimit bei 80% |
| Clamshell Überhitzung | Vertikaler Ständer für Konvektion; Monitoring der Temperatur |
| Replication Lag | Monitoring in Grafana; Alerts bei > 1 Minute Lag |
| Komplexität | Gute Dokumentation; Health Checks mit Alerts |
| macOS Update bricht Services | Auto-Updates deaktivieren; manuelles Update nach Testing |
---
## Implementierungs-Reihenfolge
1. **Hardware vorbereiten** (Phase 1)
2. **macOS konfigurieren** (Phase 2)
3. **Externe SSD einrichten** (Phase 3)
4. **Cloudflare Tunnel** (Phase 4)
5. **Ollama + große Modelle** (Phase 5.1)
6. **mana-tts migrieren** (Phase 5.2)
7. **mana-stt migrieren** (Phase 5.3)
8. **mana-image-gen migrieren** (Phase 5.4)
9. **Autostart einrichten** (Phase 7)
10. **Testing** (Phase 8)
11. **PostgreSQL Replication** (Phase 6) - Optional, später
12. **Auth Redundanz** - Optional, später
---
## Nächste Schritte
Wenn du bereit bist zu implementieren, sag mir welche Phase wir zuerst angehen sollen. Ich kann dann:
1. Die entsprechenden Scripts erstellen
2. Die Config-Dateien generieren
3. Schritt-für-Schritt Anleitung geben
**Empfehlung:** Starte mit Phase 4 (Cloudflare Tunnel) und Phase 5.1 (Ollama), da diese den größten unmittelbaren Nutzen bringen.

500
.claude/plans/windows-gpu-server-setup.md
View file

@ -1,500 +0,0 @@
# Implementierungsplan: Windows GPU-Server als AI/ML-Rechner (Stufe 1)
## Übersicht
**Ziel:** Windows-PC mit starker GPU als dedizierter AI/ML-Server einrichten.
Der Mac Mini bleibt Orchestrator für Web-Apps, Backends und Datenbanken.
Der Windows-PC übernimmt alle GPU-intensiven AI/ML-Workloads.
**Architektur:**
```
┌─────────────────────────────────────┐
│ Cloudflare Tunnels │
│ *.mana.how → Mac Mini (Primary) │
│ llm/tts/stt/img.mana.how │
│ → Windows PC (AI/ML) │
└───────────────┬─────────────────────┘
│
┌─────────────────────┴─────────────────────┐
│ │
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ MAC MINI M4 (16GB) │ │ WINDOWS GPU-SERVER │
│ "Orchestrator" │ LAN │ "AI/ML Powerhouse" │
│ 192.168.x.10 │◄───────►│ 192.168.x.11 │
├─────────────────────────────┤ ├─────────────────────────────┤
│ │ │ │
│ PostgreSQL, Redis, MinIO │ │ Ollama + CUDA │
│ mana-core-auth │ │ gemma3:27b, llama3.1:70b │
│ Alle NestJS Backends │ │ codestral:22b │
│ Alle SvelteKit Frontends │ │ │
│ Matrix Synapse + Bots │ │ mana-stt (Whisper Large) │
│ Monitoring Stack │ │ mana-tts (Kokoro + Piper) │
│ n8n, Umami │ │ mana-image-gen (FLUX.2) │
│ mana-llm (Gateway) │ │ │
│ │ │ Cloudflare Tunnel │
│ Ollama gemma3:4b (Fallback) │ │ │
└─────────────────────────────┘ └─────────────────────────────┘
```
**Was sich ändert:** Die AI-Services (Ollama, STT, TTS, Image Gen) laufen auf dem Windows-PC statt nativ auf dem Mac Mini. Der Mac Mini behält Ollama mit kleinen Modellen als Fallback. `mana-llm` (der LLM-Gateway-Container) bleibt auf dem Mac Mini, zeigt aber auf den Windows-PC.
---
## Phase 1: Windows-PC vorbereiten (1 Std)
### 1.1 Voraussetzungen prüfen
- [ ] Windows 10/11 Pro (für WSL2 + Hyper-V)
- [ ] NVIDIA GPU mit aktuellem Treiber (>= 535.x für CUDA 12)
- [ ] Mindestens 32GB RAM empfohlen
- [ ] Mindestens 200GB freier Speicher für Modelle
- [ ] Ethernet-Verbindung zum selben Netzwerk wie Mac Mini
### 1.2 Statische IP konfigurieren
```
Einstellungen → Netzwerk → Ethernet → IP-Einstellungen bearbeiten
IP-Adresse: 192.168.x.11
Subnetzmaske: 255.255.255.0
Gateway: 192.168.x.1
DNS: 1.1.1.1, 8.8.8.8
```
### 1.3 Computername setzen
```powershell
# PowerShell als Admin
Rename-Computer -NewName "mana-server-gpu"
Restart-Computer
```
### 1.4 SSH aktivieren
```powershell
# PowerShell als Admin
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
```
### 1.5 Windows Firewall — Ports freigeben
```powershell
# PowerShell als Admin — nur interne Ports fürs LAN
New-NetFirewallRule -DisplayName "Ollama" -Direction Inbound -LocalPort 11434 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Mana-STT" -Direction Inbound -LocalPort 3020 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Mana-TTS" -Direction Inbound -LocalPort 3022 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Mana-Image-Gen" -Direction Inbound -LocalPort 3023 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Mana-LLM" -Direction Inbound -LocalPort 3025 -Protocol TCP -Action Allow
```
---
## Phase 2: NVIDIA CUDA Setup (30 Min)
### 2.1 CUDA Toolkit installieren
1. NVIDIA Treiber aktualisieren (GeForce Experience oder nvidia.com)
2. CUDA Toolkit 12.x installieren: https://developer.nvidia.com/cuda-downloads
3. cuDNN installieren: https://developer.nvidia.com/cudnn
```powershell
# Prüfen ob CUDA funktioniert
nvidia-smi
```
---
## Phase 3: Ollama mit CUDA (30 Min)
### 3.1 Ollama installieren
Download: https://ollama.com/download/windows
Ollama erkennt CUDA automatisch und nutzt die GPU.
### 3.2 Ollama als Netzwerk-Service konfigurieren
Standardmäßig bindet Ollama nur an `localhost`. Für LAN-Zugriff:
```powershell
# Systemumgebungsvariable setzen (PowerShell als Admin)
[System.Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0:11434", "Machine")
[System.Environment]::SetEnvironmentVariable("OLLAMA_ORIGINS", "*", "Machine")
# Ollama neu starten
# Task Manager → Ollama beenden → Ollama App neu starten
```
### 3.3 Modelle herunterladen
```powershell
# Große Modelle (nutzen GPU VRAM)
ollama pull gemma3:27b # ~16 GB — Hauptmodell
ollama pull codestral:22b # ~14 GB — Code-Modell
ollama pull llama3.1:70b # ~40 GB — nur wenn VRAM reicht (4-bit quant)
# Kompatibilitäts-Modelle (gleich wie Mac Mini)
ollama pull gemma3:4b # ~2.5 GB
ollama pull gemma3:12b # ~7 GB
```
### 3.4 GPU-Nutzung testen
```powershell
# In einem Terminal
ollama run gemma3:27b "Sage Hallo in einem Satz"
# In einem zweiten Terminal: GPU-Auslastung prüfen
nvidia-smi
# → Ollama sollte VRAM belegen
```
### 3.5 Ollama Autostart einrichten
Ollama für Windows startet normalerweise automatisch mit dem System (Tray-App).
Falls nicht:
```powershell
# Startup-Ordner öffnen
shell:startup
# Verknüpfung zu Ollama.exe dort ablegen
```
---
## Phase 4: Cloudflare Tunnel auf Windows-PC (30 Min)
### 4.1 cloudflared installieren
```powershell
# Option A: winget
winget install Cloudflare.cloudflared
# Option B: Download
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
```
### 4.2 Tunnel erstellen
```powershell
cloudflared tunnel login
cloudflared tunnel create mana-server-gpu
# Tunnel-ID notieren!
# Credentials liegen in: C:\Users\<user>\.cloudflared\<tunnel-id>.json
```
### 4.3 DNS-Routen erstellen
```powershell
cloudflared tunnel route dns mana-server-gpu gpu.mana.how
cloudflared tunnel route dns mana-server-gpu llm.mana.how
cloudflared tunnel route dns mana-server-gpu stt-v2.mana.how
cloudflared tunnel route dns mana-server-gpu tts-v2.mana.how
cloudflared tunnel route dns mana-server-gpu img.mana.how
```
### 4.4 Tunnel-Config erstellen
**Datei:** `C:\Users\<user>\.cloudflared\config.yml`
```yaml
tunnel: <TUNNEL_ID>
credentials-file: C:\Users\<user>\.cloudflared\<TUNNEL_ID>.json
ingress:
# SSH Access
- hostname: gpu.mana.how
service: ssh://localhost:22
# Ollama LLM direkt (für mana-llm auf Mac Mini)
- hostname: llm.mana.how
service: http://localhost:11434
originRequest:
connectTimeout: 300s
# STT Service (Whisper Large)
- hostname: stt-v2.mana.how
service: http://localhost:3020
# TTS Service (Kokoro + Piper)
- hostname: tts-v2.mana.how
service: http://localhost:3022
# Image Generation (FLUX.2)
- hostname: img.mana.how
service: http://localhost:3023
# Catch-all
- service: http_status:404
```
### 4.5 Tunnel als Windows-Service installieren
```powershell
# PowerShell als Admin
cloudflared service install
# → Startet automatisch mit Windows
```
---
## Phase 5: AI-Services installieren (1-2 Std)
### 5.1 Python-Umgebung einrichten
```powershell
# Python 3.11 installieren (python.org oder winget)
winget install Python.Python.3.11
# Virtuelle Umgebungen erstellen
python -m venv C:\mana\venvs\mana-stt
python -m venv C:\mana\venvs\mana-tts
python -m venv C:\mana\venvs\mana-image-gen
```
### 5.2 mana-stt (Speech-to-Text) — Port 3020
```powershell
C:\mana\venvs\mana-stt\Scripts\activate
# CUDA-fähiges PyTorch installieren
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
# Whisper installieren
pip install faster-whisper
pip install fastapi uvicorn python-multipart
# Service-Code klonen/kopieren
git clone <repo> C:\mana\services\mana-stt
# oder: scp vom Mac Mini
```
**Windows-Service erstellen (NSSM):**
```powershell
# NSSM (Non-Sucking Service Manager) installieren
winget install NSSM
# Service registrieren
nssm install mana-stt "C:\mana\venvs\mana-stt\Scripts\python.exe" "C:\mana\services\mana-stt\main.py"
nssm set mana-stt AppDirectory "C:\mana\services\mana-stt"
nssm set mana-stt AppEnvironmentExtra "CUDA_VISIBLE_DEVICES=0" "DEVICE=cuda" "PORT=3020"
nssm set mana-stt Start SERVICE_AUTO_START
nssm start mana-stt
```
### 5.3 mana-tts (Text-to-Speech) — Port 3022
```powershell
C:\mana\venvs\mana-tts\Scripts\activate
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install kokoro-onnx piper-tts
pip install fastapi uvicorn python-multipart
# Service registrieren
nssm install mana-tts "C:\mana\venvs\mana-tts\Scripts\python.exe" "C:\mana\services\mana-tts\main.py"
nssm set mana-tts AppDirectory "C:\mana\services\mana-tts"
nssm set mana-tts AppEnvironmentExtra "DEVICE=cuda" "PORT=3022"
nssm set mana-tts Start SERVICE_AUTO_START
nssm start mana-tts
```
### 5.4 mana-image-gen (FLUX.2) — Port 3023
```powershell
C:\mana\venvs\mana-image-gen\Scripts\activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install diffusers transformers accelerate
pip install fastapi uvicorn python-multipart
# FLUX.2 Modell herunterladen (~16 GB)
# Details je nach Implementation in services/mana-image-gen/
nssm install mana-image-gen "C:\mana\venvs\mana-image-gen\Scripts\python.exe" "C:\mana\services\mana-image-gen\main.py"
nssm set mana-image-gen AppDirectory "C:\mana\services\mana-image-gen"
nssm set mana-image-gen AppEnvironmentExtra "CUDA_VISIBLE_DEVICES=0" "DEVICE=cuda" "PORT=3023"
nssm set mana-image-gen Start SERVICE_AUTO_START
nssm start mana-image-gen
```
---
## Phase 6: Mac Mini umkonfigurieren (30 Min)
### 6.1 docker-compose.macmini.yml anpassen
Die AI-Service-URLs in den Docker-Containern auf dem Mac Mini müssen auf den Windows-PC zeigen.
**Variante A — Über LAN-IP (einfach, schnell):**
```yaml
# In docker-compose.macmini.yml ändern:
# mana-llm Service
mana-llm:
environment:
OLLAMA_URL: http://192.168.x.11:11434 # War: http://host.docker.internal:11434
OLLAMA_DEFAULT_MODEL: gemma3:27b # War: gemma3:4b (jetzt größeres Modell möglich)
# chat-backend
chat-backend:
environment:
OLLAMA_URL: http://192.168.x.11:11434 # War: http://host.docker.internal:11434
# Matrix Bots
matrix-mana-bot:
environment:
OLLAMA_URL: http://192.168.x.11:11434
STT_URL: http://192.168.x.11:3020
TTS_URL: http://192.168.x.11:3022
matrix-ollama-bot:
environment:
OLLAMA_URL: http://192.168.x.11:11434
matrix-tts-bot:
environment:
TTS_URL: http://192.168.x.11:3022
matrix-stt-bot:
environment:
STT_URL: http://192.168.x.11:3020
```
**Variante B — Über Cloudflare Tunnel (robuster, funktioniert auch remote):**
```yaml
OLLAMA_URL: https://llm.mana.how
STT_URL: https://stt-v2.mana.how
TTS_URL: https://tts-v2.mana.how
```
→ Variante A ist schneller (LAN, keine Latenz durch Cloudflare), Variante B ist flexibler.
**Empfehlung:** Variante A für interne Services, Cloudflare-URLs nur für externe Zugriffe.
### 6.2 Ollama auf Mac Mini als Fallback behalten
Mac Mini behält Ollama mit kleinen Modellen (`gemma3:4b`). Falls der Windows-PC offline ist, kann `mana-llm` auf den lokalen Ollama zurückfallen. Das muss im mana-llm Service konfiguriert werden (Fallback-URL).
### 6.3 Cloudflare Tunnel auf Mac Mini anpassen
Alte STT/TTS-Routen auf dem Mac Mini entfernen oder beibehalten (als Fallback):
```yaml
# ~/.cloudflared/config.yml auf Mac Mini
# Diese Routen zeigen weiterhin auf lokale Ports:
- hostname: stt-api.mana.how # bleibt als Fallback (Mac Mini Whisper)
service: http://localhost:3020
# Neue v2-Routen gehen über den Windows-PC Tunnel
# stt-v2.mana.how → Windows-PC (konfiguriert in Phase 4)
```
---
## Phase 7: SSH-Config & Testing (30 Min)
### 7.1 SSH-Config auf Dev-Rechner erweitern
```
# ~/.ssh/config
Host mana-server-gpu
HostName gpu.mana.how
User <windows-username>
ProxyCommand /opt/homebrew/bin/cloudflared access ssh --hostname %h
```
### 7.2 Testing Checklist
```bash
# Vom Dev-Rechner aus:
# SSH
ssh mana-server-gpu
# Ollama auf Windows-PC direkt (LAN)
curl http://192.168.x.11:11434/api/version
# Ollama über Cloudflare Tunnel
curl https://llm.mana.how/api/version
# Großes Modell testen
curl http://192.168.x.11:11434/api/generate \
-d '{"model":"gemma3:27b","prompt":"Hallo!","stream":false}'
# STT Health
curl http://192.168.x.11:3020/health
# TTS Health
curl http://192.168.x.11:3022/health
# Image Gen Health
curl http://192.168.x.11:3023/health
# GPU-Auslastung remote prüfen
ssh mana-server-gpu "nvidia-smi"
```
### 7.3 Von Mac Mini aus testen
```bash
ssh mana-server # Auf Mac Mini verbinden
# Kann Mac Mini den Windows-PC erreichen?
curl http://192.168.x.11:11434/api/version
# Docker-Container können Windows-PC erreichen?
docker exec mana-service-llm curl http://192.168.x.11:11434/api/version
```
---
## Zusammenfassung: Was wo läuft
### Mac Mini (192.168.x.10) — bleibt wie gehabt, minus AI-Last
| Service | Port | Status |
|---------|------|--------|
| PostgreSQL | 5432 | Primary |
| Redis | 6379 | Primary |
| MinIO | 9000 | Unverändert |
| mana-core-auth | 3001 | Unverändert |
| Alle Backends | 3030-3040 | Unverändert |
| Alle Frontends | 5000-5100 | Unverändert |
| Matrix Stack | 4000-4090 | Unverändert |
| Monitoring | 8000-8020 | Unverändert |
| mana-llm (Gateway) | 3025 | Bleibt, zeigt auf Windows-PC |
| Ollama (Fallback) | 11434 | Behält gemma3:4b |
| mana-stt | 3020 | Kann als Fallback bleiben |
| mana-tts | 3022 | Kann als Fallback bleiben |
### Windows-PC (192.168.x.11) — nur AI/ML
| Service | Port | GPU | Beschreibung |
|---------|------|-----|-------------|
| Ollama | 11434 | CUDA | gemma3:27b, codestral:22b, llama3.1:70b |
| mana-stt | 3020 | CUDA | Whisper Large V3 |
| mana-tts | 3022 | CUDA | Kokoro + Piper |
| mana-image-gen | 3023 | CUDA | FLUX.2 |
| cloudflared | — | — | Tunnel für externe Erreichbarkeit |
---
## Implementierungs-Reihenfolge
1. **Phase 1:** Windows-PC vorbereiten (IP, SSH, Firewall)
2. **Phase 2:** CUDA Setup prüfen
3. **Phase 3:** Ollama installieren + Modelle laden + testen
4. **Phase 4:** Cloudflare Tunnel einrichten
5. **Phase 5:** AI-Services installieren (STT, TTS, Image Gen)
6. **Phase 6:** Mac Mini umkonfigurieren (URLs auf Windows-PC)
7. **Phase 7:** End-to-End testen
**Empfehlung:** Starte mit Phase 1-3 (Ollama mit GPU). Das bringt sofort den größten Nutzen — 27B-Modelle statt 4B. Die anderen AI-Services (Phase 5) können danach einzeln migriert werden.