managarten/.claude/plans/monorepo-restructure-migration.md

Monorepo Restructure Migration Plan

Target Structure

manacore-monorepo/
├── apps/                              # All product applications
│   ├── chat/
│   │   ├── apps/
│   │   │   ├── backend/               # NestJS API (@chat/backend)
│   │   │   ├── mobile/                # Expo (@chat/mobile)
│   │   │   ├── web/                   # SvelteKit (@chat/web)
│   │   │   └── landing/               # Astro (@chat/landing)
│   │   ├── packages/
│   │   │   └── chat-types/            # Shared types (@chat/types)
│   │   ├── package.json
│   │   └── CLAUDE.md
│   │
│   ├── maerchenzauber/
│   │   ├── apps/
│   │   │   ├── backend/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   ├── cards/
│   │   ├── apps/
│   │   │   ├── backend/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   ├── memoro/
│   │   ├── apps/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   ├── picture/
│   │   ├── apps/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   ├── food/
│   │   ├── apps/
│   │   │   ├── backend/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   ├── uload/
│   │   ├── apps/
│   │   │   ├── backend/
│   │   │   └── web/
│   │   └── packages/
│   │
│   ├── news/
│   │   ├── apps/
│   │   │   ├── api/
│   │   │   ├── mobile/
│   │   │   ├── web/
│   │   │   └── landing/
│   │   └── packages/
│   │
│   └── manacore/
│       ├── apps/
│       │   ├── mobile/
│       │   ├── web/
│       │   └── landing/
│       └── packages/
│
├── services/                          # Standalone microservices
│   └── mana-core-auth/                # Central auth service
│       ├── src/
│       ├── postgres/
│       ├── Dockerfile
│       └── package.json
│
├── packages/                          # Monorepo-wide shared packages
│   ├── shared-auth/
│   ├── shared-types/
│   ├── shared-utils/
│   └── ... (24 packages)
│
├── docker/
│   ├── init-db/
│   ├── prometheus/
│   ├── grafana/
│   └── minio/
│
├── docker-compose.dev.yml
├── docker-compose.yml
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

---

Phase 1: Preparation (Pre-Migration)

1.1 Create backup branch

git checkout -b backup/pre-restructure
git push origin backup/pre-restructure
git checkout main
git checkout -b feat/monorepo-restructure

1.2 Create target directories

mkdir -p apps
mkdir -p services

---

Phase 2: Move Product Applications

2.1 Move projects to apps/ folder

Source	Destination
chat/	apps/chat/
maerchenzauber/	apps/maerchenzauber/
cards/	apps/cards/
memoro/	apps/memoro/
picture/	apps/picture/
food/	apps/food/
uload/	apps/uload/
news/	apps/news/
manacore/	apps/manacore/

# Move all products to apps/
git mv chat apps/chat
git mv maerchenzauber apps/maerchenzauber
git mv cards apps/cards
git mv memoro apps/memoro
git mv picture apps/picture
git mv food apps/food
git mv uload apps/uload
git mv news apps/news
git mv manacore apps/manacore

2.2 Restructure backends to apps/ subfolder

Projects with backends at root level need restructuring:

Source	Destination
apps/chat/backend/	apps/chat/apps/backend/
apps/cards/backend/	apps/cards/apps/backend/
apps/food/backend/	apps/food/apps/backend/

# Chat: move backend into apps/
mkdir -p apps/chat/apps
git mv apps/chat/backend apps/chat/apps/backend

# Cards: move backend into apps/
mkdir -p apps/cards/apps
git mv apps/cards/backend apps/cards/apps/backend

# Food: move backend into apps/
mkdir -p apps/food/apps
git mv apps/food/backend apps/food/apps/backend

2.3 Move mana-core-auth to services/

git mv mana-core-auth services/mana-core-auth

---

Phase 3: Update Configuration Files

3.1 Update pnpm-workspace.yaml

New content:

packages:
  # Product applications
  - 'apps/*'
  - 'apps/*/apps/*'
  - 'apps/*/packages/*'

  # Standalone services
  - 'services/*'

  # Shared packages
  - 'packages/*'

3.2 Update turbo.json

No changes needed - turbo.json uses task definitions, not paths.

3.3 Update root package.json scripts

Replace scripts section:

{
	"scripts": {
		"dev": "turbo run dev",
		"build": "turbo run build",
		"test": "turbo run test",
		"lint": "turbo run lint",
		"type-check": "turbo run type-check",
		"clean": "turbo run clean",
		"format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,svelte,astro}\"",
		"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,svelte,astro}\"",

		"maerchenzauber:dev": "turbo run dev --filter=@maerchenzauber/*...",
		"manacore:dev": "turbo run dev --filter=@manacore/*...",
		"cards:dev": "turbo run dev --filter=@cards/*...",
		"memoro:dev": "turbo run dev --filter=@memoro/*...",
		"picture:dev": "turbo run dev --filter=@picture/*...",
		"uload:dev": "turbo run dev --filter=@uload/*...",
		"chat:dev": "turbo run dev --filter=@chat/*...",
		"food:dev": "turbo run dev --filter=@food/*...",
		"news:dev": "turbo run dev --filter=@news/*...",

		"dev:maerchenzauber:web": "pnpm --filter @maerchenzauber/web dev",
		"dev:maerchenzauber:landing": "pnpm --filter @maerchenzauber/landing dev",
		"dev:maerchenzauber:backend": "pnpm --filter @maerchenzauber/backend dev",
		"dev:maerchenzauber:mobile": "pnpm --filter @maerchenzauber/mobile dev",
		"dev:maerchenzauber:app": "turbo run dev --filter=@maerchenzauber/web --filter=@maerchenzauber/backend",

		"dev:manacore:web": "pnpm --filter @manacore/web dev",
		"dev:manacore:landing": "pnpm --filter @manacore/landing dev",
		"dev:manacore:mobile": "pnpm --filter @manacore/mobile dev",

		"dev:cards:web": "pnpm --filter @cards/web dev",
		"dev:cards:landing": "pnpm --filter @cards/landing dev",
		"dev:cards:backend": "pnpm --filter @cards/backend dev",
		"dev:cards:mobile": "pnpm --filter @cards/mobile dev",
		"dev:cards:app": "turbo run dev --filter=@cards/web --filter=@cards/backend",

		"dev:memoro:web": "pnpm --filter @memoro/web dev",
		"dev:memoro:landing": "pnpm --filter @memoro/landing dev",
		"dev:memoro:mobile": "pnpm --filter @memoro/mobile dev",

		"dev:picture:web": "pnpm --filter @picture/web dev",
		"dev:picture:landing": "pnpm --filter @picture/landing dev",
		"dev:picture:mobile": "pnpm --filter @picture/mobile dev",

		"dev:uload:web": "pnpm --filter @uload/web dev",

		"dev:chat:mobile": "pnpm --filter @chat/mobile dev",
		"dev:chat:web": "pnpm --filter @chat/web dev",
		"dev:chat:landing": "pnpm --filter @chat/landing dev",
		"dev:chat:backend": "pnpm --filter @chat/backend start:dev",
		"dev:chat:app": "turbo run dev --filter=@chat/web --filter=@chat/backend",

		"dev:food:mobile": "pnpm --filter @food/mobile dev",
		"dev:food:web": "pnpm --filter @food/web dev",
		"dev:food:landing": "pnpm --filter @food/landing dev",
		"dev:food:backend": "pnpm --filter @food/backend start:dev",
		"dev:food:app": "turbo run dev --filter=@food/web --filter=@food/backend",

		"dev:news:mobile": "pnpm --filter @news/mobile dev",
		"dev:news:web": "pnpm --filter @news/web dev",
		"dev:news:landing": "pnpm --filter @news/landing dev",
		"dev:news:api": "pnpm --filter @news/api start:dev",
		"dev:news:app": "turbo run dev --filter=@news/web --filter=@news/api",
		"news:db:push": "pnpm --filter @manacore/news-database db:push",
		"news:db:studio": "pnpm --filter @manacore/news-database db:studio",

		"docker:up": "docker compose -f docker-compose.dev.yml up -d postgres redis",
		"docker:up:auth": "docker compose -f docker-compose.dev.yml --profile auth up -d",
		"docker:up:chat": "docker compose -f docker-compose.dev.yml --profile chat up -d",
		"docker:up:all": "docker compose -f docker-compose.dev.yml --profile all up -d",
		"docker:down": "docker compose -f docker-compose.dev.yml --profile all down",
		"docker:logs": "docker compose -f docker-compose.dev.yml logs -f",
		"docker:logs:auth": "docker compose -f docker-compose.dev.yml logs -f mana-core-auth",
		"docker:logs:chat": "docker compose -f docker-compose.dev.yml logs -f chat-backend",
		"docker:ps": "docker compose -f docker-compose.dev.yml ps -a",
		"docker:clean": "docker compose -f docker-compose.dev.yml --profile all down -v"
	}
}

---

Phase 4: Update Docker Configuration

4.1 Update docker-compose.dev.yml

Key changes:

• mana-core-auth Dockerfile path: ./services/mana-core-auth/Dockerfile
• chat-backend Dockerfile path: ./apps/chat/apps/backend/Dockerfile

services:
  # ... postgres and redis unchanged ...

  mana-core-auth:
    profiles: ['auth', 'all']
    build:
      context: .
      dockerfile: ./services/mana-core-auth/Dockerfile
    # ... rest unchanged ...

  chat-backend:
    profiles: ['chat', 'all']
    build:
      context: .
      dockerfile: ./apps/chat/apps/backend/Dockerfile
    # ... rest unchanged ...

4.2 Update individual Dockerfiles

Each Dockerfile needs path updates for COPY commands.

services/mana-core-auth/Dockerfile:

# Update COPY paths
COPY services/mana-core-auth/package.json ./services/mana-core-auth/
COPY packages/ ./packages/
# etc.

apps/chat/apps/backend/Dockerfile:

# Update COPY paths
COPY apps/chat/apps/backend/package.json ./apps/chat/apps/backend/
COPY apps/chat/packages/ ./apps/chat/packages/
COPY packages/ ./packages/
# etc.

---

Phase 5: Update Internal References

5.1 Update CLAUDE.md files

Each project's CLAUDE.md needs path updates in documentation.

5.2 Update relative imports in code

Check for any hardcoded relative paths like:

• ../../packages/
• ../../../shared/

These may need adjustment.

5.3 Update .env files

Environment files should still work but verify paths for:

• File-based configs
• Volume mounts
• Any path references

---

Phase 6: Validation & Testing

6.1 Reinstall dependencies

rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

6.2 Verify workspace packages

pnpm ls -r --depth 0

6.3 Test turbo commands

pnpm chat:dev        # Should start all chat apps
pnpm dev:chat:web    # Should start just web
pnpm type-check      # Should check all projects

6.4 Test Docker

pnpm docker:up:all
pnpm docker:ps
pnpm docker:logs

6.5 Build all projects

pnpm build

---

Phase 7: Commit & Merge

7.1 Commit changes

git add .
git commit -m "refactor: restructure monorepo with apps/ and services/ directories

- Move all product applications under apps/
- Move standalone microservices under services/
- Standardize backend location to apps/{project}/apps/backend/
- Update pnpm-workspace.yaml for new structure
- Update docker-compose paths
- Update root package.json scripts"

7.2 Create PR

gh pr create --title "refactor: monorepo restructure" --body "..."

---

Rollback Plan

If issues arise:

git checkout main
git branch -D feat/monorepo-restructure

---

Migration Checklist

• Create backup branch
• Create apps/ and services/ directories
• Move 9 product projects to apps/
• Move backends into apps/{project}/apps/backend/
• Move mana-core-auth to services/
• Update pnpm-workspace.yaml
• Update root package.json scripts
• Update docker-compose.dev.yml paths
• Update docker-compose.yml paths (production)
• Update Dockerfiles COPY paths
• Update CLAUDE.md documentation
• Reinstall dependencies (pnpm install)
• Test turbo dev commands
• Test Docker builds
• Run type-check
• Run build
• Commit and create PR

---

Estimated Impact

Item	Count
Directories to move	10
Config files to update	5-6
Dockerfiles to update	~6
package.json scripts	~40 (most unchanged)
CLAUDE.md files	~10

Risk Level: Medium - Many file moves but package names unchanged Estimated Time: 2-4 hours with testing