Workspace packages (Phase 2 overlay)

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

TL;DR

• The repo is now an npm workspace with one package per architectural unit:
  • encoreos-app / encoreos-public — Turborepo / Vercel Microfrontends keys only (placeholder packages/* with no encoreos tier metadata; see MICROFRONTENDS_RUNBOOK.md)
  • @encoreos/platform — Platform Foundation
  • @encoreos/shared — leaf-level reusable UI / lib
  • @encoreos/core-{ce,cl,fa,fm,fw,gr,hr,it,lo,pm,rh} — one per domain core
• Source files have not moved. Each packages/<name>/package.json references its source under src/<scope>/<slug>/ via the encoreos.sourceDirectory field. Existing @/cores/hr/... imports keep working unchanged.
• Each package’s package.json declares what it is allowed to depend on. npm run audit:package-boundaries enforces the constitution at the package-metadata layer:
  • Cores depend only on @encoreos/platform and @encoreos/shared.
  • @encoreos/platform depends on @encoreos/shared only.
  • @encoreos/shared depends on neither platform nor any core.
  • CL is downstream: no other core may declare a dep on @encoreos/core-cl (constitution §1.4).
• This unlocks Turborepo --filter so a PR touching one core can turbo run typecheck --filter=@encoreos/core-hr...[origin/prod] and skip cache work for the other 11.
• It also unlocks the dependency graph view (npm ls --workspaces --depth=0, Turborepo’s --graph) so reviewers can see “who depends on whom” at a glance.

​

Why an overlay (and not a full physical migration)?

​

Layout

packages/
  encoreos-app/
    package.json                 # name: "encoreos-app" — microfrontends / Turborepo key only (no src)
  encoreos-public/
    package.json                 # name: "encoreos-public" — microfrontends / Turborepo key only (no src)
  platform/
    package.json                 # name: "@encoreos/platform"
                                 # encoreos.sourceDirectory: "../../src/platform"
  shared/
    package.json                 # name: "@encoreos/shared"
                                 # encoreos.sourceDirectory: "../../src/shared"
  core-ce/
    package.json                 # name: "@encoreos/core-ce"; deps on platform+shared
  core-cl/
    package.json                 # name: "@encoreos/core-cl"; deps on platform+shared;
                                 # encoreos.downstreamOnly: true (constitution §1.4)
  core-fa/  ...                  # 11 cores total
  docs/                          # pre-existing Docusaurus site; NOT in workspaces glob

src/                             # source files unchanged; this is what packages reference
  cores/{ce,cl,...,rh}/
  platform/
  shared/

{
  "workspaces": [
    "packages/encoreos-app",
    "packages/encoreos-public",
    "packages/platform",
    "packages/shared",
    "packages/core-*"
  ]
}

​

What this package model enforces

​

At the package-metadata layer (this PR’s contribution)

{
  "name": "@encoreos/core-hr",
  "encoreos": {
    "tier": "core",            // "platform" | "shared" | "core"
    "coreSlug": "hr",
    "sourceDirectory": "../../src/cores/hr",
    "constitutionRefs": ["§1.2", "§1.3", "§1.4"]
  },
  "dependencies": {
    "@encoreos/platform": "*", // npm workspaces use literal '*'
    "@encoreos/shared": "*"
  }
}

​

At the import-statement layer (unchanged)

• Package metadata catches intent before code is written (“you can’t even declare a dep on another core”).
• Import scan catches accidents in code already written (“someone wrote import {} from '@/cores/cl/...' inside src/cores/hr/”).

​

What it unlocks immediately

• Turborepo --filter — Phase-1.A’s turbo.json already declares typecheck, lint:ci, test:unit, build tasks. Now that workspaces exist, those tasks can be filtered:
  # Only run typecheck for HR core and its dependencies
  npx turbo run typecheck --filter=@encoreos/core-hr
  
  # Affected-since-prod (PR-shaped invocation)
  npx turbo run typecheck lint:ci --filter=...[origin/prod]
  
• npm ls --workspaces --depth=0 — instant view of declared dependency edges.
• Per-package package.json evolution — when a core needs a new dependency, it declares it locally (closer to the consumer). The root package.json doesn’t grow unbounded.
• Codegen / scaffolding hooks can target packages individually instead of grepping src/cores/.

​

What it does NOT do (yet)

• Per-package tsc --build. TS project references with composite: true would let tsc --build skip untouched packages, but composite requires emitting declaration files; our app uses noEmit: true. A future ADR can switch to a hybrid model (composite for downstream consumers; noEmit for the entry app), but that’s out of scope here.
• Per-package Vite build. Vite still bundles src/main.tsx as one app. That’s the right behavior until Phase 3 (Microfrontends) splits zones.
• Physical file moves. src/cores/hr/... is still where HR’s source lives.
• eslint-plugin-boundaries. Phase 1.C remains deferred. The structural audit + the existing import-layer audit cover the same ground without adding to the current lint:ci warning budget (--max-warnings 1100 in package.json).

​

Migrating to a full physical layout (Phase 2.B, deferred)

1. git mv src/cores/hr/** packages/core-hr/src/**
2. Update packages/core-hr/package.json encoreos.sourceDirectory → ./src
3. Add packages/core-hr/tsconfig.json extending the root, with composite: true, outDir: dist, include: ["src/**/*"].
4. Update root tsconfig.app.json paths: change "@/cores/hr/*": ["./src/cores/hr/*"] to "@/cores/hr/*": ["./packages/core-hr/src/*"].
5. Add packages/core-hr to root tsconfig.references.json references list.
6. Run npm run typecheck && npm run lint:ci && npm run test:unit && npm run build. Land that core’s PR.
7. Repeat for the next core.

​

Operational notes

​

npm install is now idempotent across packages

​

Adding a new core (future)

1. mkdir packages/core-{slug}
2. Update the CORES list in scripts/dev/generate-core-package-jsons.mjs.
3. npm run packages:regenerate-cores writes the new packages/core-{slug}/package.json.
4. npm install to wire workspaces.
5. npm run audit:package-boundaries to verify.

​

Removing a core (future)

1. Delete packages/core-{slug}/
2. Remove from the CORES list in the generator.
3. npm install.

​

Why encoreos.sourceDirectory and not main / exports?

​

See also

• packages/*/package.json — the actual package definitions
• scripts/audit/audit-package-boundaries.ts
• scripts/dev/generate-core-package-jsons.mjs
• scripts/utils/check-architecture.js — the existing import-scan auditor (unchanged)
• docs/recommendations/DEV_VELOCITY_AND_ARCHITECTURE_PLAN_2026-04-22.md § 5.4 — the original Phase-2 plan (lands via PR #137)
• docs/architecture/decisions/ADR-016-workspace-packages-overlay.md — formal ADR for this design choice
• Constitution §1 (architecture and module boundaries)
• docs/development/TURBOREPO_USAGE.md — Phase 1.A companion (lands via PR #139)