The Monorepo Mental Model Repository, workspace, package, application, dependency graph, and why TaskFlow uses one repository without becoming one giant process.
The Monorepo Mental Model Before we create files, we need precise language. Most monorepo confusion comes from using repository, workspace, project, application and package as if they mean the same thing. They do not.
One repository, multiple projects A monorepo is one version-controlled repository that contains multiple related projects. pnpm calls the package-management layer a workspace. Git knows about files and commits; pnpm knows which package.json files belong to one dependency graph.
Repository vs The .git directory makes taskflow a Git repository. pnpm-workspace.yaml makes workspace the same folder a pnpm workspace root. One folder can be both, but the responsibilities are different.
contains contains
apps/web apps/apiFigure 1 - Git owns history; pnpm owns the multi-package dependency workspace
Four words you must separate Term Meaning in this course
Repository The entire taskflow folder tracked by Git.
Workspace The pnpm-managed set of packages declared by pnpm-workspace.yaml.
Application A deployable product such as apps/web or apps/api.
Package A directory with its own package.json that participates in the workspace. An app is also a package from pnpm's perspective.
Why one repository for TaskFlow? The frontend and backend are separate applications, but they evolve together. A single repository lets one commit represent a coherent system change: an API contract update, the matching frontend change, and any shared validation change can be reviewed together. • One version-control history for related full-stack changes. • One workspace lockfile for consistent dependency resolution. • One place for repository-wide scripts and policy. • Easy local linking when a real shared package appears later. • A clear boundary between deployable apps and reusable packages.
Why not one giant application? A monorepo does not mean one runtime process. Next.js and NestJS will remain independent applications with different ports, build outputs, environment variables and deployment targets. They share a repository, not a process.
taskflow repository
contains contains
apps/web - Next.js apps/api - NestJSbuild/deploy build/deploy
frontend deployment API deployment
The root is a control plane The root package.json should coordinate the workspace, not become a dumping ground for application dependencies. React belongs to the web package. NestJS belongs to the API package. A formatter or repository-wide build orchestrator may eventually belong at the root because it acts across packages.
A useful ownership question Which package imports this dependency at runtime or build time? If the answer is apps/web, install it there. If the answer is apps/api, install it there. If the tool genuinely coordinates the entire repository, the root may own it.
apps/ versus packages/ Directory Responsibility Examples later
apps/ Deployable or runnable applications web, api, workerpackages/ Reusable code/config used by more than one validators, shared types only when earned workspace package
The dependency graph is the architecture you can compile Once packages depend on one another, the workspace becomes a graph. Healthy graphs point toward reusable foundations rather than creating cycles.
apps/web ----> packages/validators <---- apps/apiapps/web ----> packages/shared ----> apps/api ----> apps/webCycle warning pnpm can detect cyclic workspace dependencies. A cycle usually means responsibilities are mixed. Do not hide the warning; inspect which package should stop depending on which other package.
One lockfile, strict declarations pnpm workspaces use a shared lockfile by default. That gives the repository one exact dependency-resolution snapshot while still keeping each package honest: a package should only access dependencies it declares in its own package.json.
This matters because a monorepo should make dependency boundaries more visible, not less visible.
When a monorepo is the wrong tool • Projects have unrelated release cycles, ownership and security boundaries. • Teams cannot share repository access for compliance reasons. • The repository becomes a dumping ground for unrelated experiments. • Tooling complexity exceeds the coordination benefit.
TaskFlow is a good fit because the web and API are parts of one product and will share contracts, versions and learning checkpoints.
Mental-model checkpoint • Git repository != pnpm workspace, even when they share the same root folder. • A workspace package has its own package.json. • An application is a package with a deployable runtime responsibility. • The root coordinates; it should not absorb every dependency. • Shared packages are introduced by reuse pressure, not by folder aesthetics.
Monorepo Mental Model matters because it changes a real boundary in TaskFlow. The goal is to understand the inputs, owner, observable output, and failure modes before adding more abstraction.
Restate the goal of “Monorepo Mental Model” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: repository root → workspace package → dependency graph → task runner → artifact. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: TaskFlow repository root with apps/web, apps/api, shared packages, workspace metadata, root scripts, and clean Git hygiene.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
Input -> owner -> transformation -> observable output -> failure evidenceDo not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Return to the nearest observable boundary: input, network, process log, database, or rendered UI. Compare actual evidence with the predicted path.
Change one variable at a time and reproduce the original failure after the fix; otherwise you have correlation, not diagnosis.
Without copying the final source, create a second small scenario that applies “Monorepo Mental Model” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Create the repository root and initialize Git before generating applications.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Installing app-only dependencies at workspace root
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.