drop-monorepo-refactor-plan

Plan: Drop Monorepo Refactor (src/ → apps/+packages/)

MC: #10051 Owner: John (orchestrator) + CodeCraft + Proveo + Skillforge Estimated total: ~15h CodeCraft + 2h validation + 1h docs = ~18h fleet time Strategy: 4-PR staged migration (NOT atomic) per Petter's research Research: /tmp/drop-monorepo-research-10051.md (347 lines, Petter Graff)

Research Summary

Drop monorepo currently uses npm workspaces under src/ (3 registered: src/shared, src/drop-api, src/drop-app; src/drop-mobile is on separate release cycle, NOT in workspace config but referenced in 3 mobile workflows). Migrating to apps/+packages/ requires touching 80+ hardcoded paths across 8 GitHub Actions workflows, 2 root Dockerfiles, buildspec.yml (just merged in PR #3), 2 docker-compose files, and root package.json lint-staged.

Top 3 production risks

1. Dockerfile.drop-app:59,67 — WORKDIR /app/src/drop-app baked into Next.js standalone runner stage. Silent build success / runtime fail on App Runner cold start.
2. ci.yml:49-53 paths-filter must update atomically with rename. Wrong order = silent CI skip = unreviewed code reaches main.
3. Dockerfile.api uses raw source-copy to /shared/ (not workspace symlinks) — structurally inconsistent with Dockerfile.drop-app. Audit separately.

Why multi-PR (NOT atomic)

• Each PR is reviewable, revertable, testable independently
• CI workflow update (PR 3) is highest-risk single change → its own PR
• Pre-Finanstilsynet: every CI/security-gate change deserves explicit review
• 4 conflict-able PRs > 1 monster PR with 80+ touched paths

Objective

Restructure Drop monorepo to industry-standard Turborepo/pnpm convention (apps/ for deployables, packages/ for shared libs) WITHOUT introducing behavior changes, downtime, or production deploys breaking. Land in 4 staged PRs over 2-3 days, with staging validation before prod merge.

Team Orchestration

Team Members

Step-by-Step Tasks

Phase 1 — Internal packages rename (low risk, isolated)

Task 1: PR 1 — Rename src/shared → packages/shared

• Owner: B1 (codecraft)
• BlockedBy: none (research deliverable already done)
• Branch: feat/monorepo-pr1-packages-shared
• Scope:
  • git mv src/shared packages/shared (preserves history)
  • Root package.json workspaces array: "src/shared" → "packages/shared"
  • npm install regenerate lockfile (in Linux container per ZAKON LOCKFILE PORTABILITY)
  • Verify apps/drop-app/node_modules/@drop/shared symlink resolves (post-PR-2; for PR 1 verify root node_modules/@drop/shared resolves)
  • Update lint-staged glob if src/shared/ referenced
• Acceptance:
  • npm install --ignore-scripts --no-audit exit 0
  • cd src/drop-app && npx tsc --noEmit exit 0 (shared resolves via root workspace)
  • cd src/drop-api && npx tsc --noEmit exit 0
  • CI Quality Gate REQUIRED green on PR
  • No file outside packages/shared/ and package.json + package-lock.json modified

Task 2: Gemini review PR 1

• Owner: R1
• BlockedBy: 1
• Acceptance: VERDICT: APPROVE

Task 3: Squash merge PR 1 to main

• Owner: John
• BlockedBy: 2
• Post-merge: verify main CI green

Phase 2 — Apps rename + Docker (highest production risk)

Task 4: PR 2 — Rename src/drop-* → apps/drop-* + Dockerfile + buildspec updates

• Owner: B2 (codecraft)
• BlockedBy: 3 (PR 1 merged)
• Branch: feat/monorepo-pr2-apps-docker
• Scope:
  • git mv src/drop-app apps/drop-app, src/drop-api apps/drop-api, src/drop-mobile apps/drop-mobile
  • Update root package.json workspaces: "src/drop-api" → "apps/drop-api", "src/drop-app" → "apps/drop-app"
  • Update lint-staged globs (3 patterns) + cd src/drop-* commands
  • Update Dockerfile.drop-app: ALL src/drop-app → apps/drop-app, src/shared → packages/shared. CRITICAL: both WORKDIR /app/src/drop-app lines (59 + 67) → /app/apps/drop-app
  • Update Dockerfile.api: src/drop-api → apps/drop-api, src/shared → packages/shared AND /monorepo/src/shared/ → /monorepo/packages/shared/ (the absolute-path hack)
  • Update buildspec.yml: 7 occurrences of src/drop-app → apps/drop-app, src/shared → packages/shared
  • Update docker-compose.yml + docker-compose.dev.yml build contexts + bind mounts
  • Verify next.config.ts outputFileTracingRoot: ../../ still resolves to repo root from apps/drop-app/ (it does — same depth)
  • Local Docker build MANDATORY (ZAKON LOCAL DOCKER BUILD): docker buildx build --platform linux/amd64 -f Dockerfile.drop-app . exit 0
• Acceptance:
  • npm install --ignore-scripts --no-audit exit 0
  • cd apps/drop-app && npx eslint . 0 errors
  • cd apps/drop-app && npx tsc --noEmit exit 0
  • docker buildx build --platform linux/amd64 -f Dockerfile.drop-app . exit 0 (LOCAL evidence required)
  • docker buildx build --platform linux/amd64 -f Dockerfile.api . exit 0
  • CI Quality Gate REQUIRED green on PR
  • No CI workflow file modified in this PR (saved for PR 3)
  • No src/ directory deleted yet (saved for PR 4)

Task 5: Gemini review PR 2

• Owner: R1
• BlockedBy: 4
• Acceptance: VERDICT: APPROVE
• Special review focus: Dockerfile WORKDIR lines, Dockerfile.api absolute path, lockfile linux-x64 variants

Task 6: Squash merge PR 2 to main — CAUTION

• Owner: John
• BlockedBy: 5
• Note: This DOES trigger deploy.yml auto-deploy. Production App Runner will build with new paths. Monitor aws apprunner describe-service until RUNNING status. If deploy fails, immediate rollback via CF CNAME flip + previous SHA redeploy per DEPLOY-MAP.md.
• Pre-merge mandatory: external curl -sI https://app.getdrop.no shows current production health
• Post-merge mandatory: external curl -sI https://app.getdrop.no shows healthy within 10min of CF CNAME flip

Phase 3 — CI workflows update (silent skip risk)

Task 7: PR 3 — Update 8 GitHub Actions workflows

• Owner: B3 (codecraft)
• BlockedBy: 6 (PR 2 merged + production verified RUNNING)
• Branch: feat/monorepo-pr3-ci-workflows
• Scope:
  • ci.yml: paths-filter (5 lines), working-directory, cache-dependency-path, cd commands, artifact paths
  • deploy.yml: docker build context path
  • deploy-staging.yml: paths, working-directory, cache-dependency-path, playwright report path
  • hotfix.yml: working-directory x2, cache-dependency-path
  • deploy-aws.yml: working-directory, docker build context
  • mobile-ci.yml: paths-filter, working-directory x3, cache-dependency-path, artifact path
  • mobile-deploy.yml: paths-filter, working-directory, git add path
  • mobile-release.yml: working-directory, cache-dependency-path, VERSION_FILE path, git add path
• Acceptance:
  • All 8 workflow files modified, no other code changes
  • CI Quality Gate REQUIRED green on PR
  • gh workflow view "CI — Quality Gate" runs against new paths
  • mobile-ci.yml triggers on apps/drop-mobile/** paths-filter when mobile code changed (test by including 1-line mobile change in PR)

Task 8: Gemini review PR 3

• Owner: R1
• BlockedBy: 7
• Acceptance: VERDICT: APPROVE
• Special review focus: paths-filter glob accuracy (silent CI skip is the danger)

Task 9: Squash merge PR 3

• Owner: John
• BlockedBy: 8
• Note: deploy-staging.yml manual workflow_dispatch test BEFORE merge, against PR HEAD SHA, to confirm staging path resolution

Phase 4 — Cleanup + production validation

Task 10: PR 4 — Delete legacy src/ directory + ALAI memory updates

• Owner: B4 (codecraft)
• BlockedBy: 9 (PR 3 merged + main CI green)
• Branch: feat/monorepo-pr4-cleanup
• Scope:
  • git rm -r src/ (now empty after PR 1 + PR 2 moves)
  • Update BUILD-BLUEPRINT.md repo structure section + build commands
  • Update DEPLOY-MAP.md paths
  • Update RUNBOOK.md if any path references
  • Update project/architecture/*.md references
  • Update ~/.claude/projects/-Users-makinja/memory/MEMORY-products.md Drop entry
  • Update any ~/.claude/projects/-Users-makinja/memory/project_drop_*.md referring to old paths
• Acceptance:
  • find . -path "./src" -type d empty
  • grep -r "src/drop-" --include="*.md" --include="*.yml" --include="*.json" 0 hits in repo (excluding old git history)
  • CI Quality Gate REQUIRED green on PR

Task 11: Proveo validation — STAGING (pre-merge)

• Owner: V1 (proveo)
• BlockedBy: 10 (PR 4 ready, but NOT merged yet)
• Action: trigger deploy-staging.yml workflow_dispatch against PR 4 head SHA
• Acceptance:
  • Staging App Runner reaches RUNNING state within 15min
  • curl -s https://staging.getdrop.no/api/health | jq .status == "ok"
  • Playwright smoke test (login + dashboard + send-money flow) passes
  • No new Sentry errors in staging post-deploy
  • Evidence written to /tmp/proveo-monorepo-staging-10051.json

Task 12: Gemini review PR 4

• Owner: R1
• BlockedBy: 11
• Acceptance: VERDICT: APPROVE

Task 13: Securion fintech security audit (pre-prod merge)

• Owner: V3 (securion / Parisa Tabriz)
• BlockedBy: 11
• Scope: monorepo path rename security implications — secrets accidentally exposed via different paths, .gitignore coverage, JWT/auth boundary integrity, OWASP Top 10 quick check
• Acceptance:
  • No secret leaks introduced by path changes
  • Auth middleware paths still correct
  • No new attack surface introduced
  • Report at /tmp/securion-monorepo-10051.md

Task 14: Squash merge PR 4 to main

• Owner: John
• BlockedBy: 12, 13
• Triggers: deploy.yml auto-deploy to production
• Pre-merge mandatory: external curl baseline, gh run list main shows green
• Post-merge mandatory: monitor App Runner deploy

Task 15: Proveo validation — PRODUCTION

• Owner: V2 (proveo)
• BlockedBy: 14
• Action: post-deploy verification per DEPLOY-MAP.md ZAKON PI2 protocol
• Acceptance:
  • curl -s https://app.getdrop.no/api/health | jq .status == "ok"
  • Playwright screenshot of dashboard (live data load)
  • No CI deploy.yml errors
  • No Sentry error spike in 30min post-deploy
  • App Runner blue/green flip verified
  • Evidence at /tmp/proveo-monorepo-prod-10051.json + screenshot

Task 16: Skillforge documentation

• Owner: D1 (skillforge)
• BlockedBy: 15
• Scope:
  • BookStack page "Drop Monorepo Architecture" — apps/+packages/ structure, deploy paths, conventions
  • Memory entry project_drop_monorepo_refactor_2026-XX-XX.md with lessons learned + path migration patterns
  • Update ~/system/rules/zakon-local-docker-build.md if monorepo-specific gotchas surfaced
• Acceptance:
  • BookStack page exists and synced
  • Memory entry created
  • MEMORY.md index updated

Risk Register

Rollback Plan (per PR)

Validation Checkpoints (cumulative across phases)

After EACH PR merge to main:

1. gh run list --branch main --limit 1 last run = SUCCESS for "CI — Quality Gate"
2. curl -sI https://app.getdrop.no returns HTTP 200
3. aws apprunner describe-service --service-arn <drop-web-arn> Status: RUNNING
4. No new Sentry errors in 15min after deploy
5. git log --oneline main shows clean linear history (squash merges)

After PR 4 (final cleanup): 6. find /Users/makinja/ALAI/products/Drop -type d -name "src" returns 0 results 7. Repo size reduced (lockfile + node_modules can re-regenerate in fresh clone) 8. Skillforge BookStack page accessible at https://docs.alai.no

Estimate of Total Time

Add 30% buffer for failure recovery iterations = ~18h fleet, 3 calendar days.

Required Follow-ups

1. backend/ legacy directory at repo root — confirm dead code in separate MC, then either rename or delete. NOT in scope of this MC.
2. mobile-release.yml cross-references src/drop-app/src/config/app-versions.json from within mobile workflow — clarify ownership boundary in followup.
3. Migration to true Turborepo (turbo.json) or pnpm — separate MC. This refactor only renames paths, does NOT change tooling.
4. Sentry post-deploy verification — if source maps un-symbolicate, separate MC for Sentry config update.

Per ZAKON PLAN compliance

• Validation task — Tasks 11 (Proveo staging) + 15 (Proveo prod) — end-to-end Playwright + curl + Sentry monitoring (NOT dry-run)
• Documentation task — Task 16 (Skillforge) — BookStack page + memory entry

Approval

Plan ready for CEO review. To execute:

/build-plan ~/system/specs/drop-monorepo-refactor-plan.md

Or dispatch first phase manually:

/mehanik "Drop monorepo PR 1: packages/shared rename + workspace config" /Users/makinja/ALAI/products/Drop <new_MC_id>