0005 - Adopt a pnpm Monorepo

Status: Accepted Date: 2026-07-12 Author: Manuel Nucci Supersedes: ADR 0001's dedicated-repository decision only

Context

Feel Pro Club previously maintained fpc-shared, fpc-api, fpc-app, and fpc-docs as separate Git repositories. That separation made cross-package features expensive to coordinate:

• Shared changes required local links or a registry release before API and App could consume them.
• A single product change produced multiple pull requests, lockfiles, CI runs, and version updates.
• Repository-level hooks, dependency overrides, agent instructions, and workflows drifted.
• It was difficult to validate a shared-contract change against every consumer before merging.

The separation of specifications from implementation in ADR 0001 was useful organizationally, but a dedicated Git repository is not required to preserve the specification-driven workflow.

Decision

We will maintain the four project packages in one Git repository using a plain pnpm workspace:

• Keep the existing fpc-shared/, fpc-api/, fpc-app/, and fpc-docs/ directory boundaries and package-specific build/test configuration.
• Preserve the complete history of the former repositories and namespace unique historical refs where needed.
• Resolve @feelproclub/shared internally with workspace:*; do not publish it to a package registry.
• Install from one root lockfile and centralize repository-level hooks, dependency overrides, ownership, and CI configuration.
• Use dependency-aware CI: Shared changes validate Shared plus API and App consumers; package-only changes run scoped checks; root configuration changes run all checks.
• Keep PRDs in fpc-docs/prd/ as the source of truth. The implementation order remains Shared → API → App → tests.
• Keep dev as the integration/default branch and main as production. Preserve unfinished feature work on its feature branch.

This ADR supersedes only ADR 0001's decision that specifications must live in a dedicated repository. ADR 0001's specification-driven workflow, source-of-truth rules, and acceptance-criteria-to-tests policy remain in force.

Consequences

Positive

• Cross-workspace changes can be reviewed, tested, and merged atomically.
• Shared contracts can be validated against all consumers without publishing intermediate versions.
• One lockfile and one repository-level toolchain reduce drift.
• CI can skip unaffected work while retaining a stable required check.
• Documentation and implementation can change together without weakening PRD ownership.

Negative

• The repository and root CI workflow are larger and require explicit path/dependency rules.
• Deployment platforms must use monorepo root contexts and workspace-aware build commands.
• Repository permissions and ownership are broader than in isolated repositories.
• The history-preserving import creates a non-linear initial commit graph.

Mitigations

• Retain workspace-local instructions, architecture documents, tests, and package boundaries.
• Test change detection, first-push behavior, Docker builds, and deployment paths in CI.
• Use CODEOWNERS and protected dev/main branches.
• Keep source repositories read-only until CI and deployment cutover are verified.