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

Monorepo Architecture Reorg Handoff

This handoff is the coordination entrypoint for the Reactive Resume architecture reorganization. It intentionally references the implementation plan instead of duplicating it.

Primary Plan

• Plan: docs/superpowers/plans/2026-05-14-monorepo-architecture-reorg.md
• Worklog: docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md
• Branch at start: feat/explore-hono-orpc-migration

Current Operating Rules

• Preserve existing unrelated local changes:
  • apps/server/package.json
  • package.json
  • packages/api/package.json
  • packages/env/package.json
  • packages/utils/package.json
  • pnpm-lock.yaml
• Do not use git reset --hard or destructive checkout commands.
• Use green internal commits if committing is requested/appropriate.
• Use root AGENTS.md as the final normative architecture source of truth.
• Do not create local package READMEs for architecture rules unless a package has unavoidable operational constraints.

Suggested Skills for Future Agents

• subagent-driven-development for executing one task slice with review gates.
• executing-plans for sequential execution from the plan.
• documentation-writer for AGENTS.md, ADR, and public architecture docs.
• handoff when pausing or delegating a task outside Codex.
• turborepo when editing turbo.json, package tags, or task graph rules.
• context7-mcp if checking current docs for library/framework behavior.

Delegation Guidance

External agents should be handed exactly one task from the plan plus this handoff path. They should report:

• Status: DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT
• Files changed
• Tests/commands run
• Any plan deviations
• Follow-up tasks needed

Task Ownership Status

• Task 0 Coordination Artifacts: done
• Task 1 Pure Resume Domain Package: done
• Task 2 DOCX Package: done
• Task 3 PDF Package Browser/Server Generation Surface: done
• Task 4 MCP Package and Shared Tool Contracts: done
• Task 5 API Feature Reorganization: done
• Task 6 Server Adapter Reorganization: done
• Task 7 Domain-First Web Reorganization: done
• Task 8 Dialog Registry Rework: done
• Task 9 Boundary Enforcement: done
• Task 10 Documentation and Source of Truth: done
• Task 11 Final Validation and Handoff: done

Architecture Decisions Already Locked

• @reactive-resume/schema is Zod/types only.
• @reactive-resume/resume owns pure resume-domain behavior.
• @reactive-resume/ai owns model contracts, not DB-backed agent runtime.
• Agent runtime remains in packages/api/features/agent.
• MCP uses an in-process oRPC RouterClient.
• MCP tools move to canonical unprefixed snake_case names, no old aliases.
• @reactive-resume/pdf owns PDF generation helpers but not PDF.js viewer UI.
• apps/web uses domain-first features and generic-only src/components.
• packages/db remains centralized.

Latest Task 1 Result

• Created @reactive-resume/resume with source-consumed exports:
  • @reactive-resume/resume/patch
  • @reactive-resume/resume/icons
• Moved JSON Patch behavior/tests and social network icon mapping/tests out of @reactive-resume/utils.
• Updated consumers in packages/ai, packages/api, packages/db, packages/import, and apps/web.
• Removed old utils exports for ./resume/patch and ./network-icons.
• Removed fast-json-patch from @reactive-resume/utils and @reactive-resume/ai; it now belongs to @reactive-resume/resume.
• Task 2 later removed @reactive-resume/schema from @reactive-resume/utils after moving DOCX code into @reactive-resume/docx.

Latest Task 2 Result

• Created @reactive-resume/docx with source-consumed root export @reactive-resume/docx.
• Moved the DOCX builder, HTML conversion, link utilities, section renderers, and colocated tests from packages/utils/src/resume/docx to packages/docx/src.
• Updated web DOCX export callers and the export-section test mock to import from @reactive-resume/docx.
• Removed the old @reactive-resume/utils/resume/docx export and removed docx plus @reactive-resume/schema from @reactive-resume/utils.
• Validation passed for @reactive-resume/docx tests/typecheck, @reactive-resume/utils typecheck, web typecheck, focused web export test command, and focused Biome check.

Latest Task 3 Notes

• Added @reactive-resume/pdf/browser and @reactive-resume/pdf/server exports.
• createResumePdfBlob({ data, template, resolveSectionTitle }) delegates to pdf(<ResumeDocument ... />).toBlob().
• createResumePdfFile({ data, filename, template, resolveSectionTitle }) delegates to renderToBuffer(<ResumeDocument ... />) and preserves the existing File response body shape.
• Lingui locale loading stays in the web-local wrappers under apps/web/src/features/resume/export; those wrappers resolve section titles and pass resolveSectionTitle into the package helpers.
• The PDF.js viewer/canvas components remain in web. apps/web/src/features/resume/preview/preview.browser.tsx now calls the web-local blob wrapper instead of importing @react-pdf/renderer directly.
• The authenticated PDF export path now reaches @reactive-resume/pdf/server through packages/api/src/features/resume/export.ts; apps/server consumes the explicit API feature export instead of owning PDF rendering logic directly.
• Validation passed for @reactive-resume/pdf tests/typecheck, web typecheck, server typecheck, focused web PDF export/viewer tests, and focused Biome check.

Latest Task 4 Notes

• Created @reactive-resume/mcp with source-consumed exports for the compact public surface plus direct subpaths for server card, tool names, tools, prompts, and resources.
• Moved MCP tools, prompts, resources, server-card generation, tool annotations, and colocated tests from apps/web/src/routes/mcp/-helpers to packages/mcp/src.
• apps/server/src/mcp/handler.ts and apps/server/src/openapi/metadata.ts now import from @reactive-resume/mcp; server-side MCP execution still uses the injected in-process oRPC RouterClient.
• Canonical MCP tool names are unprefixed snake_case. Key renames: read_resume replaces the old get-resume tool name, and apply_resume_patch replaces the old patch tool name. No reactive_resume_* aliases remain.
• Added @reactive-resume/ai/tools/resume-tool-contracts and reused its JSON Patch operations schema from MCP while keeping MCP-specific id context in the MCP input schema.
• Validation passed for @reactive-resume/mcp tests/typecheck, server typecheck, @reactive-resume/ai typecheck, focused Biome check, and the app-to-app import scan.

Latest Task 5 Notes

• packages/api/src is now organized by feature/capability under packages/api/src/features.
• The root router still exports the same top-level API contract from packages/api/src/routers/index.ts, but it imports feature routers from features/*/router.
• Agent modules now live under features/agent, with separate procedure modules for threads, messages, attachments, and actions; run-state lives in runs.ts, tool construction in tools.ts, and the remaining shared orchestration stays in service.ts.
• Resume modules now live under features/resume, with capability procedure modules for CRUD, tags, statistics, analysis, events, sharing, and export. Access helpers and resume update events are feature-owned.
• The authenticated PDF download procedure moved to packages/api/src/features/resume/export.ts and calls @reactive-resume/pdf/server.
• @reactive-resume/api no longer exports ./services/* or ./helpers/*; explicit exports now cover routers, context, flags type, resume runtime/export, and storage runtime.
• apps/server imports storage and the PDF procedure from explicit API feature exports. apps/web API imports remain type-only.
• Follow-up risk: features/agent/service.ts and features/resume/service.ts are still large DB-backed facades. They are feature-owned now, but further splitting should be handled as behavior-preserving follow-up work with targeted tests around run lifecycle, patch transactions, notifications, and storage cleanup.
• Validation passed for API tests/typecheck, server typecheck, web typecheck, MCP typecheck, focused Biome, and old service/helper import/export scans.

Latest Task 6 Notes

• apps/server/src now reads as a runtime adapter app:
  • http: route composition, auth/health HTTP handlers, common header/cookie helpers
  • rpc: oRPC fetch handler and request-locale extraction
  • mcp: MCP auth, per-request server setup, and streamable HTTP transport handler
  • openapi: OpenAPI handler plus OAuth/OpenID/MCP well-known metadata
  • static: upload serving, /schema.json, and apps/web/dist static/SPA fallback serving
  • startup: database migrations and local-storage path checks
• apps/server/src/index.ts now only re-exports createApp, runs startup checks, computes the port, and starts the Hono server.
• The route order and public paths from the previous index.ts were preserved, including /api/rpc, /api/openapi, /api/auth/*, /api/health, /uploads/*, /schema.json, /auth/oauth, /mcp, /.well-known/*, and the web-dist fallback.
• Server-side API imports remain on explicit runtime exports only; no @reactive-resume/api/services/* or apps/web/src imports were introduced.
• Validation passed for server test/typecheck during implementation. Final Task 6 validation commands should still be listed in the worklog/final response after the executing agent's last run.

Latest Task 7 Slice 1 Notes

• Resume-owned web code now starts under apps/web/src/features/resume:
  • builder/draft.ts owns the builder resume draft store/hooks.
  • preview/* owns the builder preview shell, PDF.js canvas renderer, shared preview helpers/tests, and dashboard thumbnail PDF rendering helpers.
  • export/pdf-document*.tsx owns web-local PDF document/blob/file wrappers around @reactive-resume/pdf.
  • public/* owns the public resume view, public PDF.js viewer, CSS, and tests.
• The old generic resume component folder and public-route private component folder were removed after their files moved.
• Direct pdfjs-dist imports are expected only under apps/web/src/features/resume; do not move them into packages/pdf.
• The public resume route remains responsible for loader/error/head composition, keeps ssr: "data-only", and lazy-loads @/features/resume/public/public-resume.
• The builder preview route keeps ssr: false and lazy-loads the preview page composition.
• Remaining Task 7 work should continue moving non-resume web domains out of generic components/routes. Task 8 still owns dialog registry decomposition beyond import updates caused by the draft-store move.

Latest Task 7 Slice 2 Notes

• App-shell code now starts under feature folders:
  • apps/web/src/features/command-palette owns the command palette implementation and tests.
  • apps/web/src/features/theme owns the theme provider, combobox, toggle button, and tests.
  • apps/web/src/features/locale owns the locale combobox and tests.
  • apps/web/src/features/user owns the user dropdown.
• Auth route UI now lives under apps/web/src/features/auth; route files under apps/web/src/routes/auth keep redirects/search validation and compose the feature pages.
• Settings page UI now lives under apps/web/src/features/settings; route files under apps/web/src/routes/dashboard/settings keep dashboard header composition and redirects. job-search.tsx remains route-only because it is already just a redirect shim.
• The old @/components/{command-palette,theme,locale,user} import paths should not be reintroduced; current consumers import from @/features/*.
• apps/web/src/components now contains remaining generic primitive/screen folders only.
• Task 8 still owns dialog registry decomposition; this slice did not decompose dialog definitions.

Latest Task 8 Notes

• apps/web/src/dialogs/store.ts remains the single global dialog runtime and still exports useDialogStore plus DialogProps<T> for existing callers.
• Dialog schemas now compose through apps/web/src/dialogs/schemas.ts from domain-owned schema entries in dialogs/auth/schema.ts, dialogs/api-key/schema.ts, and dialogs/resume/schema.ts.
• Dialog rendering now composes through apps/web/src/dialogs/renderers.tsx from domain-owned renderer registries in dialogs/auth/registry.tsx, dialogs/api-key/registry.tsx, and dialogs/resume/registry.tsx.
• apps/web/src/dialogs/manager.tsx only imports the dialog shell, renderDialog, and the global store; it no longer imports every dialog implementation directly.
• No settings/auth-specific dialog tests existed beyond the shared dialog store and resume template tests.

Latest Task 9 Notes

• turbo.json now has executable boundaries config:
  • Global dependencies deny web and server, preventing package-to-app and app-to-app dependency edges.
  • Root test tools are explicit implicitDependencies: vitest, @testing-library/jest-dom, @testing-library/react, and @testing-library/user-event.
  • Tag rules cover app, server, browser, universal, domain, and UI layers.
• Workspace turbo.json files now exist for both apps and every package. Each extends root config with extends: ["//"] and declares tags used by the root boundaries.
• Every workspace vitest.config.ts keeps its legitimate root shared config import with // @boundaries-ignore root shared Vitest config immediately above import { createVitestProjectConfig } from "../../vitest.shared";.
• biome.json now enables style.noRestrictedImports for forbidden cross-workspace source/path imports:
  • @reactive-resume/*/src/**
  • apps/**
  • packages/**
• biome.json also registers tooling/grit/no-cross-workspace-src-imports.grit, which flags import/export/dynamic import sources that reach into another workspace's src tree.
• apps/web/tsconfig.json no longer maps @reactive-resume/ui/* directly to ../../packages/ui/src/*; the web app uses @reactive-resume/ui package exports instead.
• Files changed by Task 9:
  • turbo.json
  • apps/*/turbo.json
  • packages/*/turbo.json
  • biome.json
  • tooling/grit/no-cross-workspace-src-imports.grit
  • apps/web/tsconfig.json
  • apps/server/vitest.config.ts
  • apps/web/vitest.config.ts
  • packages/*/vitest.config.ts
  • docs/superpowers/worklogs/2026-05-14-monorepo-architecture-reorg.md
  • docs/superpowers/handoffs/2026-05-14-monorepo-architecture-reorg.md
• Validation passed:
  • pnpm exec turbo boundaries
  • pnpm exec biome check biome.json turbo.json tooling/grit/no-cross-workspace-src-imports.grit apps/web/tsconfig.json apps/server/turbo.json apps/web/turbo.json packages/*/turbo.json
  • pnpm --filter web typecheck
  • pnpm --filter @reactive-resume/api typecheck
  • pnpm --filter server typecheck
• Remaining risks:
  • The Turbo tag set is intentionally coarse and may need finer per-package rules as future browser/server package classes settle.
  • The GritQL plugin only inspects code import/export sources; keep the package export-map and tsconfig scans in the final validation list.
  • The root shared Vitest config remains an intentional boundary ignore; moving it behind a package export would be a separate test-infra cleanup.

Latest Task 10 Notes

• AGENTS.md is now the operational source of truth for package roles, runtime tags, import rules, placement decisions, and validation commands.
• docs/contributing/architecture.mdx is now a public contributor overview of the current monorepo layout instead of the removed single-src architecture.
• docs/adr/0001-workspace-boundaries.md records the rationale for domain-first packages, explicit export maps, turbo boundaries, and Biome/Grit import enforcement.
• MCP user docs already list canonical unprefixed tool names from Task 4. AI Agent tool docs already list read_resume and apply_resume_patch; no Task 10 changes were needed there.
• Follow-up documentation audit on 2026-05-15 reconciled AGENTS and public docs with the final apps/server Hono adapter shape, current Node/pnpm prerequisites, Base UI wording, provider-native web research behavior, and the current env schema.
• Docs validation available in-repo is limited:
  • Stale-text scan passed except expected ORPCClient diagram labels.
  • Biome ignored Markdown/MDX and reported that no files were processed for the docs paths.
  • No dedicated docs build/check script exists in package.json.

Latest Task 11 Notes

• Final cleanup after pnpm knip:
  • Removed stale app dependencies from apps/server/package.json and apps/web/package.json.
  • Deleted the unused web server PDF wrapper at apps/web/src/features/resume/export/pdf-document.server.tsx.
  • Removed unnecessary exported markers from internal helper functions/constants.
  • Added pdfExportRateLimit to packages/api/src/features/resume/export.ts.
  • Removed unused jobs rate-limit middleware entries that no current router uses.
• Final validation commands passed:
  • pnpm install --lockfile-only
  • pnpm install
  • pnpm exec biome check .
  • pnpm exec turbo boundaries
  • pnpm knip
  • pnpm typecheck
  • pnpm test
  • pnpm build
• pnpm knip still prints a non-failing configuration hint: src/server.ts apps/web knip.json Refine entry pattern (no matches).
• Useful review anchors:
  • Architecture rules: AGENTS.md, docs/contributing/architecture.mdx, docs/adr/0001-workspace-boundaries.md.
  • Boundary enforcement: turbo.json, workspace turbo.json files, biome.json, tooling/grit/no-cross-workspace-src-imports.grit.
  • API feature tree: packages/api/src/features.
  • Server adapter tree: apps/server/src/{http,rpc,mcp,openapi,static,startup}.
  • Web feature tree: apps/web/src/features.