Reactive-Resume/docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md

Monorepo Architecture Reorganization Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use subagent-driven-development or executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Status note: This implementation plan has been executed and may contain historical intermediate paths. Use AGENTS.md, docs/contributing/architecture.mdx, docs/adr/0001-workspace-boundaries.md, and docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md for current architecture guidance.

Goal: Reorganize Reactive Resume into clear domain/package boundaries so server, web, API, MCP, PDF, resume-domain logic, and documentation are easier to debug and enforce.

Architecture: This is one PR with green internal commits. Packages expose role-based explicit public surfaces, web routes become thin shells over domain features, API code is colocated by feature/capability, and boundary rules prevent app-to-app source imports and private package source imports.

Tech Stack: pnpm 11, Turborepo 2, TypeScript/tsgo, Vite, React 19, TanStack Router, oRPC, Drizzle, React PDF, PDF.js, MCP SDK, Biome/GritQL, Vitest.

---

Non-Negotiable Decisions

• Root AGENTS.md is the single normative architecture source of truth.
• docs/adr/0001-workspace-boundaries.md records rationale only; it must not duplicate the full operational rule set.
• docs/contributing/architecture.mdx is a descriptive overview, not a second source of truth.
• Keep one PR and green internal commits; no compatibility wrappers or old import-path shims.
• Preserve existing unrelated user changes in manifests and lockfile. Do not reset or revert them.
• Keep apps/server and apps/web split. apps/server may serve apps/web/dist; app-to-app src imports are banned.
• apps/web may import packages/api types only. Runtime imports from packages/api in web are banned.
• apps/server may import explicit runtime exports from packages/api.
• Tests remain colocated with moved code.

Task 0: Coordination Artifacts

Files:

• Modify: docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md

• Modify: docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md

• Modify: docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md

• Keep this plan updated when implementation discoveries force refinements.

• Keep the handoff file focused on current task ownership and next-agent startup context.

• Keep the worklog append-only with commands, validation results, blockers, and changed ownership decisions.

Task 1: Pure Resume Domain Package

Goal: Create @reactive-resume/resume for pure resume-domain behavior, keeping @reactive-resume/schema validation-only and @reactive-resume/utils generic.

Files:

• Create: packages/resume/package.json

• Create: packages/resume/tsconfig.json

• Create: packages/resume/vitest.config.ts

• Move/create: packages/resume/src/patch.ts

• Move/create: packages/resume/src/icons.ts

• Move tests from packages/utils/src/resume/patch.test.ts

• Move tests for packages/utils/src/network-icons.test.ts

• Modify importers/callers currently using @reactive-resume/utils/resume/patch

• Modify importers/callers currently using @reactive-resume/utils/network-icons

• Modify packages/utils/package.json

• Modify root workspace manifests/lockfile as needed

• Create the new package using the repo's source-consumed package pattern.

• Move JSON Patch schema/types/application/comparison/error into @reactive-resume/resume/patch.

• Move social network to icon-name mapping into @reactive-resume/resume/icons.

• Update all runtime and test imports.

• Remove @reactive-resume/schema dependency from @reactive-resume/utils.

• Run pnpm --filter @reactive-resume/resume test.

• Run pnpm --filter @reactive-resume/resume typecheck.

• Run targeted typechecks for known consumers: @reactive-resume/api, @reactive-resume/ai, web.

Task 2: DOCX Package

Goal: Create @reactive-resume/docx as the dedicated DOCX export package.

Files:

• Create: packages/docx/package.json

• Create: packages/docx/tsconfig.json

• Create: packages/docx/vitest.config.ts

• Move: packages/utils/src/resume/docx/* to packages/docx/src/*

• Modify web export callers currently using @reactive-resume/utils/resume/docx

• Modify package dependencies/lockfile

• Create @reactive-resume/docx with explicit export "." or "./builder" as appropriate.

• Move DOCX implementation and tests unchanged except import paths.

• Update web callers to import DOCX export from @reactive-resume/docx.

• Remove DOCX dependencies from @reactive-resume/utils if no longer used there.

• Run pnpm --filter @reactive-resume/docx test.

• Run pnpm --filter @reactive-resume/docx typecheck.

• Run focused web export tests/typecheck.

Task 3: PDF Package Browser/Server Generation Surface

Goal: Keep @reactive-resume/pdf focused on document/template/font rendering and pure generation adapters. Do not move PDF.js viewer UI into the PDF package.

Files:

• Create: packages/pdf/src/browser.tsx

• Create: packages/pdf/src/server.tsx

• Modify: packages/pdf/package.json

• Modify: web PDF generation callers currently using apps/web/src/libs/resume/pdf-document.tsx

• Modify: apps/server/API PDF download code after Task 5

• Add data-plus-options generation APIs:

  • createResumePdfBlob({ data, template, resolveSectionTitle })
  • createResumePdfFile({ data, filename, template, resolveSectionTitle })

• Keep Lingui locale loading in apps/web; pass resolveSectionTitle into PDF helpers.

• Keep ResumeDocument as the underlying render surface.

• Add/update tests for the browser/server helpers where practical.

• Run pnpm --filter @reactive-resume/pdf test.

• Run pnpm --filter @reactive-resume/pdf typecheck.

Task 4: MCP Package and Shared Tool Contracts

Goal: Extract MCP implementation from web route helpers into @reactive-resume/mcp; share model-facing tool contracts from @reactive-resume/ai.

Files:

• Create: packages/mcp/package.json

• Create: packages/mcp/tsconfig.json

• Create: packages/mcp/vitest.config.ts

• Move: apps/web/src/routes/mcp/-helpers/* to packages/mcp/src/*

• Create/modify: packages/ai/src/tools/resume-tool-contracts.ts

• Modify: packages/ai/package.json

• Modify: apps/server/src/handlers/mcp.ts

• Modify: apps/server/src/handlers/metadata.ts

• Remove old web helper imports

• Move MCP tools/prompts/resources/metadata card generation and tests into @reactive-resume/mcp.

• Keep MCP execution through an injected/in-process oRPC RouterClient.

• Rename MCP tools to canonical unprefixed snake_case names such as list_resumes, read_resume, apply_resume_patch.

• Do not keep old reactive_resume_* aliases.

• Use shared base tool contracts from @reactive-resume/ai, with MCP-specific schema extensions for explicit context fields such as resumeId.

• Update MCP docs/card version and cache-refresh guidance later in documentation tasks.

• Run pnpm --filter @reactive-resume/mcp test.

• Run pnpm --filter @reactive-resume/mcp typecheck.

• Run pnpm --filter server typecheck.

Task 5: API Feature Reorganization

Goal: Move packages/api/src from technical layers into feature/capability modules with explicit public exports.

Files:

• Reorganize under packages/api/src/features/*

• Modify: packages/api/src/routers/index.ts

• Modify: packages/api/package.json

• Modify consumers in apps/server, apps/web type imports, and packages

• Split features/agent into threads, messages, attachments, actions, runs, and tools.

• Split features/resume by capability: crud, tags, statistics, analysis, access, events, sharing, export.

• Move authenticated PDF download procedure into features/resume/export; it calls @reactive-resume/pdf/server.

• Keep Drizzle schema centralized in packages/db; API features consume schema but do not own table definitions.

• Remove ./services/* and ./helpers/* wildcard exports.

• Add explicit runtime exports required by apps/server.

• Preserve apps/web API imports as type-only.

• Run pnpm --filter @reactive-resume/api test.

• Run pnpm --filter @reactive-resume/api typecheck.

• Run pnpm --filter server typecheck.

• Run pnpm --filter web typecheck.

Task 6: Server Adapter Reorganization

Goal: Make apps/server read as a runtime adapter app.

Files:

• Reorganize apps/server/src into http, rpc, mcp, openapi, static, startup

• Modify: apps/server/src/index.ts

• Modify: apps/server/package.json if imports/dependencies change

• Move handlers into adapter folders.

• Keep server logic thin: auth/session/HTTP transport/static serving/startup.

• Use explicit API runtime exports only.

• Keep serving apps/web/dist allowed.

• Run pnpm --filter server test.

• Run pnpm --filter server typecheck.

Task 7: Domain-First Web Reorganization

Goal: Move web code into domain/workflow feature trees so routes become thin shells.

Files:

• Create/reorganize under apps/web/src/features/resume/*

• Create/reorganize under apps/web/src/features/{command-palette,theme,locale,user,auth,settings,dialogs}/*

• Modify route imports and tests

• Move resume domain code into workflow folders:

  • builder
  • preview
  • public
  • dialogs
  • sections
  • templates
  • export
  • pdf-viewer

• Move PDF.js viewer/canvas UI into web resume feature, not @reactive-resume/pdf.

• Keep route files responsible for URL params, loaders, redirects, SSR settings, and composition.

• Leave apps/web/src/components with generic app-level primitives/screens only.

• Move app shell concerns into separate features: command palette, theme, locale, user.

• Move auth workflows into features/auth and settings sections into features/settings.

• Run focused moved tests.

• Run pnpm --filter web typecheck.

Slice 1 notes:

• Moved resume builder draft state, builder preview, PDF.js canvas preview, dashboard thumbnail PDF rendering helpers, public resume PDF viewer, and web-local PDF document wrappers under apps/web/src/features/resume/*.
• Removed apps/web/src/components/resume and apps/web/src/routes/$username/-components; the public resume route now lazy-loads from features/resume/public.
• Kept PDF.js viewer/canvas code in apps/web/src/features/resume and left @reactive-resume/pdf limited to PDF generation helpers.
• Broader Task 7 remains open for non-resume web feature moves and deeper dialog registry work owned by Task 8.

Slice 2 notes:

• Moved command palette, theme, locale, and user shell components/tests from apps/web/src/components/* to apps/web/src/features/{command-palette,theme,locale,user} and updated consumers.
• Moved auth route UI, layout, and social auth component into apps/web/src/features/auth, leaving auth route files as guard/search/composition wrappers.
• Moved settings page UI and authentication/integration subcomponents into apps/web/src/features/settings, leaving settings route files as dashboard-header/composition wrappers; job-search stayed route-only because it is already a redirect shim.
• apps/web/src/components now contains only the remaining generic primitive/screen folders.
• Task 8 still owns dialog registry decomposition; this slice only updated imports around existing dialog usage.

Task 8: Dialog Registry Rework

Goal: Keep one central dialog runtime but make domain modules own their dialog definitions/renderers.

Files:

• Modify/create under apps/web/src/features/dialogs

• Modify/create domain dialog registry modules under relevant features

• Modify root dialog manager import

• Replace the single giant discriminated union/manager import hub with composable domain registries.

• Keep one global dialog store/runtime.

• Each domain exports its schema entries and renderers.

• Preserve existing dialog behavior and tests.

• Run dialog-focused tests.

• Run pnpm --filter web typecheck.

Task 9: Boundary Enforcement

Goal: Make architectural rules executable.

Files:

• Modify: turbo.json

• Modify: biome.json

• Create: tooling/grit/no-cross-workspace-src-imports.grit

• Modify package manifests/tsconfigs to remove forbidden direct source path aliases

• Add turbo boundaries package/runtime rules.

• Add a Biome GritQL plugin/rule for forbidden cross-workspace src imports and path aliases.

• Enforce subpath runtime tags: root exports environment-neutral; browser/server code behind explicit subpaths.

• Allow wildcard exports only for role-approved leaf libraries such as UI components/hooks.

• Run pnpm exec turbo boundaries.

• Run a focused Biome boundary check.

Task 10: Documentation and Source of Truth

Goal: Document the final architecture without duplicating rules in multiple places.

Files:

• Modify: AGENTS.md

• Create: docs/adr/0001-workspace-boundaries.md

• Modify: docs/contributing/architecture.mdx

• Modify: docs/guides/using-the-mcp-server.mdx if MCP tool names change

• Modify: docs/guides/ai-agent-tools.mdx if shared tool naming changes

• Update root AGENTS.md with the normative workspace map, import rules, package roles, runtime tags, validation commands, and placement decision tree.

• Add ADR rationale for boundaries and rejected alternatives.

• Refresh public architecture docs as overview only.

• Update MCP docs to mention canonical unprefixed tool names and client refresh/cache-clear guidance.

• Avoid local package READMEs for architecture rules unless unavoidable.

• Run docs-related checks available in the repo.

Task 11: Final Validation and Handoff

Goal: Finish with a validated branch and external-agent-ready handoff.

Files:

• Modify: docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md

• Modify: docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md

• Run focused checks listed in earlier tasks.

• Run final repo checks:

  • pnpm install --lockfile-only
  • pnpm exec biome check .
  • pnpm exec turbo boundaries
  • pnpm knip
  • pnpm typecheck
  • pnpm test
  • pnpm build

• Update the handoff with completed tasks, remaining risks, commands run, and useful file paths.

• Dispatch final review if subagents are available.