An engineering monorepo, explained

FM Lab Monorepo

A long-lived workspace for learning modern software engineering, testing ideas in isolation, and keeping only what proves its value. The portfolio is a by-product; the engineering record is the point.

54 milestones delivered in sequence · 49 recorded decisions · 27 workspaces

Learn → Experiment → Promote

The repository's adoption rule, and how it has actually played out.

  1. Learn

    A technology enters only with a stated learning objective or engineering responsibility, recorded in milestones and decisions.

  2. Experiment

    The rule reserves labs/ for isolated experiments, yet labs/ holds 0 workspaces today. Experiments were built instead as 4 standalone playground workspaces and as independent product slices.

  3. Promote

    Shared code is promoted only after a second product needs it. Capabilities such as storage and search were extracted from working product slices, never designed up front.

The engineering journey

Three phases drawn as one line. Each station is a milestone in delivery order; the spacing shows sequence, not time.

  1. Phase 1

    Foundation and documentation ecosystem

    M0 to M7.1

    The repository foundation and a documentation ecosystem: one immutable platform, public SDK packages, and the applications built on them.

    40 milestones · 11 workspaces introduced · 35 decisions
  2. Phase 2

    Product vertical slices

    M8.0 to M8.4

    Independent product vertical slices, with shared capabilities extracted only after they proved themselves in more than one product.

    5 milestones · 7 workspaces introduced · 5 decisions
  3. Phase 3

    Framework and runtime breadth

    M9.0 to M10.1 · ongoing

    The same boundaries tested across other frameworks, runtimes, and languages, with design tokens that belong to no framework.

    9 milestones · 9 workspaces introduced · 9 decisions

See every milestone

Architecture

Dependencies flow one way. Applications use packages, packages never use applications, and the playgrounds stand alone.

12 applications · 11 packages · 4 playgrounds

Open the architecture map

Where to start reading

Four routes through the documentation, each for a different reader.

Portfolio visitors

5 documents

What the repository is and why it is shaped this way, in about five minutes.

  1. Architecture OverviewArchitecture note · docs/architecture/overview.md
  2. Adopt a Vertical Slice StrategyDecision · ADR-036
  3. Prefer Delayed Extraction Across Vertical SlicesDecision · ADR-037
  4. M8.2 Shared Foundations Acceptance ReviewAcceptance review · docs/acceptance/M8.2-shared-foundations-review.md
  5. Introduce a Derived Repository AtlasDecision · ADR-049

Engineers

9 documents

Boundaries, decisions, and how capabilities were extracted without sharing product behavior.

  1. Dependency RulesArchitecture note · docs/architecture/dependency-rules.md
  2. Documentation SystemArchitecture note · docs/architecture/documentation-system.md
  3. Build One Immutable Documentation PlatformDecision · ADR-005
  4. Adopt a Vertical Slice StrategyDecision · ADR-036
  5. Prefer Capability Extraction Over Framework ExtractionDecision · ADR-038
  6. Preserve Domain Ownership Across Shared CapabilitiesDecision · ADR-039
  7. Prefer Framework-Neutral CapabilitiesDecision · ADR-041
  8. Shared FoundationsGuide · docs/guides/shared-foundations.md
  9. Notes Vertical Slice ArchitectureGuide · docs/guides/notes-architecture.md

Contributors

4 documents

Install, run, validate, and change the repository.

  1. ContributingRepository guide · CONTRIBUTING.md
  2. Contribution WorkflowGuide · docs/guides/contribution-workflow.md
  3. Development ServersGuide · docs/guides/development-servers.md
  4. Documentation WorkflowGuide · docs/guides/documentation-workflow.md

Documentation SDK users

4 documents

Adopt the public documentation packages; the Documentation Website covers the rest.

  1. Getting Started with Repository DocumentationGuide · docs/guides/getting-started-documentation.md
  2. Documentation SDK API ReferenceGuide · docs/guides/documentation-sdk-api-reference.md
  3. Documentation Package ReferenceGuide · docs/guides/documentation-packages-reference.md
  4. Documentation Extension ContractsGuide · docs/guides/documentation-extension-contracts.md

Technology

Languages, runtimes, and frameworks exactly as the manifests declare them, with no versions guessed.

Language
  • TypeScript
  • C#
  • Python
Runtime
  • Node.js
  • Bun
  • Deno
  • .NET
Frameworks and libraries
  • Astro
  • Next.js
  • SvelteKit
  • Vite
  • ASP.NET Core
  • FastAPI
  • Nuxt

See the full technology matrix

Run it locally

Every development server has a fixed port and refuses to start when that port is taken, instead of moving somewhere else.

Prerequisites

  • Node.js 24.18.0, from .nvmrc
  • pnpm@11.15.1, provisioned by Corepack
  • Only for the playgrounds: Bun, Deno, .NET 10.0, Python >=3.13,<3.14

Install

Run these once, from the repository root.

nvm use corepack enable pnpm install

Root commands

  • pnpm devStart the Atlas development server.
  • pnpm dev:atlasThe same as pnpm dev, named explicitly.
  • pnpm dev:allCheck every prerequisite, then start all development servers. Nothing starts if a check fails.

Start one workspace with pnpm --filter <workspace> dev.

All commands and ports

Engineering decisions

49 architecture decisions are recorded. These eight explain the repository best.

  1. ADR-005
    Build One Immutable Documentation Platform

    One immutable platform object is the backbone every documentation tool reads from.

  2. ADR-019
    Introduce a Documentation SDK

    A single high-level SDK turned internal packages into a product others can adopt.

  3. ADR-036
    Adopt a Vertical Slice Strategy

    Products are built end to end as vertical slices instead of layer by layer.

  4. ADR-037
    Prefer Delayed Extraction Across Vertical Slices

    Shared code is extracted only after a second product proves the need.

  5. ADR-038
    Prefer Capability Extraction Over Framework Extraction

    What gets shared are capabilities such as storage and search, never framework code.

  6. ADR-044
    Introduce Runtime Independence Validation

    Runtime independence is tested with real services, not assumed.

  7. ADR-048
    Introduce Framework-Neutral Design Tokens

    Visual consistency comes from framework-neutral tokens, not a shared component library.

  8. ADR-049
    Introduce a Derived Repository Atlas

    This Atlas derives its inventories from the repository instead of maintaining copies.

Browse all decisions

Three sites, one set of documents

The Atlas, the Documentation Website, and the Knowledge Hub read the same documents for different readers.

Orientation

@fm/atlas

You are here

Orients first-time readers: what the repository contains, how it grew, and where to read next. Every list on it is derived from the repository when the site is built.

Run locally: pnpm --filter @fm/atlas dev · http://127.0.0.1:3308
SDK documentation

@fm/documentation-site

The product documentation for the Documentation SDK. It renders every canonical document, with search, a relationship graph, and upgrade guidance, using the same public SDK it documents.

Run locally: pnpm --filter @fm/documentation-site dev · http://127.0.0.1:3301
Handbook

@fm/knowledge-hub

The handbook: a small set of curated documents that connect engineering ideas with the repository's decisions and code.

Run locally: pnpm --filter @fm/knowledge-hub dev · http://127.0.0.1:3300