0006 - Adopt Conventional Workspace Directories

Status: Accepted Date: 2026-07-12 Author: Manuel Nucci Supersedes: ADR 0005's directory-layout clause only

Context

ADR 0005 consolidated Feel Pro Club into a pnpm monorepo while retaining the former repository names as top-level directories. Those names describe packages, but they do not distinguish deployable applications from reusable packages and leave documentation alongside application folders without a conventional grouping.

The monorepo now needs a layout that makes ownership, deployment boundaries, and reusable code immediately clear without changing package identities, imports, or public behavior.

Decision

Use the following repository layout:

apps/
├── api/                 # package: fpc-api
└── app/                 # package: fpc-app
packages/
└── shared/              # package: @feelproclub/shared
docs/                    # package: fpc-docs

• Keep package names, exports, pnpm filters, API routes, schemas, and environment-variable names unchanged.
• Keep root-level tooling, CI configuration, deployment manifests, and scripts at the repository root.
• Update all path-based automation, deployment configuration, documentation links, and agent instructions to use these paths.
• Preserve Git history through file moves; do not retain compatibility symlinks for the former directories.

This supersedes only ADR 0005's decision to retain the former package-named top-level directory boundaries. ADR 0005's monorepo, workspace, CI, and branch decisions remain in force.

Consequences

Positive

• Deployable applications are grouped under apps/ and reusable code under packages/.
• Documentation has a stable, conventional top-level location.
• The filesystem communicates architectural ownership without changing package-level interfaces.

Negative

• Path-based CI, deployment configuration, documentation, and local tooling must be updated together.
• Existing developer commands that cd into former directories need new paths.

Mitigations

• Preserve package names and root pnpm --filter commands so build, test, and import interfaces remain stable.
• Validate CI classification, Docker and deployment paths, VitePress edit links, and all stale-path references as part of the move.