Lesson 0002 · ~12 minutes

Architecture map: workspace → graph → tasks

One skill: sketch a monorepo as workspace + projects + graph + tasks + targets — using moon’s names so setup and moon run won’t feel alien later.

← Lesson 1 Lesson 3 → Architecture sheet Glossary Resources Mission

Win for this lesson

You can draw five boxes for any monorepo (workspace, projects, graph, tasks, targets) and point to where shared vs local config lives — still without installing moon.

1. Five layers (keep this map)

Lesson 1: monorepo needs relationships + tooling, not only folders. moon names the pieces like this (concepts index):

Workspace — repo root: projects + toolchain + tasks + VCS. Marked by a .moon folder (moon: Workspace).
Projects — each app/lib/tool is a project with a stable ID, optional moon.* config (moon: Projects).
Project graph — DAG of “who depends on whom.” Explicit dependsOn and/or language-implied edges (e.g. package.json workspace deps) (moon: Project graph).
Tasks — commands run in a project’s context (lint, test, build, dev) (moon: Tasks.
Targets — scope:task, e.g. app:lint. How you run work and declare task-to-task deps (moon: Targets).

Package manager workspaces still install/link packages. The orchestration layer is graph + tasks + targets.

2. Shared vs local configuration

Standardization lives in the split between workspace and project:

Workspace-level (shared)
- .moon/workspace.* — which paths are projects (globs/map).
- .moon/tasks/** — tasks defined once, inherited by many projects ((task inheritance).
- .moon/toolchains.* — pinned Node/Rust/… versions so laptop ≈ CI (toolchain).
Project-level (local)
- moon.* in the project root — local tasks, overrides, dependsOn, tags/layer/language.
- Same-name local + inherited task merges (append/prepend/replace strategies) — not always a hard overwrite.

Mission hook

“Easier maintenance” ≈ put the boring same-everywhere work in .moon/tasks + toolchain, keep product-specific commands in project moon.*.

3. Targets you will actually say out loud

You type / write	Meaning
`moon run app:lint`	Project `app`, task `lint`
`moon run :lint`	`lint` in all projects
`deps: ['^:build']`	Before this task, run `build` on each project this one depends on
`deps: ['typecheck']`	Same project’s `typecheck` first (`~`)

Mental model: project graph = structure; targets = how work is addressed on that structure.

4. Why the graph exists (not just a diagram)

moon’s project graph docs list real jobs: feed the task graph, Docker layering, project sync, and affected projects in CI (what the graph is used for). Without edges you fall back to “run everything” — collocation pain from lesson 1.

5. Practice

Equal-length options; retrieve the map from memory.

Question 1

In moon terms, what is the workspace?

Question 2

What is a target?

Question 3

You want the same lint task on every TypeScript library. Best home?

Question 4

In task config, what does deps: ['^:build'] mean?

6. Primary source

Recommended: moon — Concepts (skim Workspace, Project, Task, Target, Toolchain, Task inheritance). Then open the architecture sheet when you forget a name.

Optional depth: Project graph (explicit vs implicit edges; what the graph powers).

Ask your teacher Map a real repo (e.g. trio-moon) onto these five layers, or ask what to put in workspace tasks vs project tasks. Chat is part of the course.