Repository Design Decisions & Anti-Patterns Why the TaskFlow root stays boring, which abstractions we rejected, and the evidence that would justify adding them later.
Repository Design Decisions and Anti-Patterns The strongest repository architecture is usually the one with the fewest unexplained moving parts. This book records the decisions Phase 02 made, the alternatives we rejected, and the signals that would justify changing those decisions later.
Decision 1 - One monorepo for web and API Choice Why now Revisit when...
One Git repository The applications form one product and access, compliance, ownership or change together release boundaries become truly independent
pnpm workspace Built-in multi-package management already a future orchestrator must solve solves our current problem measurable task-graph/caching pain
One shared lockfile Consistent resolution and easier review almost never for this single-product workspace without a concrete reason
Decision 2 - Keep the root boring The root is policy and orchestration. A root package that accumulates React, NestJS, database libraries and application utilities has erased the very ownership boundaries the monorepo was meant to clarify.
Smell If you cannot tell whether a dependency is frontend, backend, or repository tooling because everything is installed at the root, the package boundaries are already failing.
Decision 3 - Do not create packages before reuse exists A folder named shared is not architecture. A shared package earns its existence when it owns one coherent responsibility that at least two consumers need and when keeping duplicate implementations would create real drift or risk.
Good future package candidate A validators package can become reasonable after web and API both need the same task input schema and we intentionally want one authoritative contract.
Weak package candidate A utils package that collects unrelated date helpers, string functions, API wrappers and business rules becomes a dependency magnet. Prefer colocating helpers with the feature or responsibility they support until a coherent reusable package emerges.
Anti-pattern - the prebuilt enterprise tree packages/ common/ core/ domain/ infrastructure/ shared/ utils/ types/ config/
The problem is not the names themselves. The problem is creating them before the system contains responsibilities that require those boundaries. Empty architecture makes navigation harder while teaching nothing about why the abstraction exists.
Anti-pattern - framework dependencies at root taskflow/package.json react next @nestjs/core prisma @prisma/client
This makes the root look convenient while hiding which app truly depends on each technology. The correct default is package ownership: frontend libraries in apps/web, backend/database libraries in apps/api initially.
Anti-pattern - multiple nested repositories Running git init inside apps/web or apps/api creates independent histories unless intentionally using submodules or another advanced strategy. That would undermine the course monorepo model. One .git directory at taskflow/ is the expected state.
Anti-pattern - generated files without review Framework generators are useful, but generated output is still your codebase. Starting in Phase 03, every generator step must be followed by tree inspection and Git diff review before the generated code is accepted.
no clear gain repeated pressure
Decision record for future phases • Phase 03 creates apps/web and lets Next.js own frontend dependencies. • Phase 04 creates apps/api and lets NestJS/Fastify own backend dependencies. • Prisma remains inside apps/api when introduced; no packages/db is created by default. • A shared validators package is considered only when real cross-app schema reuse appears. • Turborepo is considered only when pnpm orchestration becomes measurably insufficient. • Deployment remains independent per app even though source history is shared.
Engineering checkpoint A clean Phase 02 repository is intentionally unimpressive to look at. That is a strength. Every file at the root has a concrete responsibility, and there is almost nothing to delete. The sophistication will come from working software and earned boundaries, not from an elaborate empty tree.
Authentication answers who the request represents. Treating decoded or client-supplied identity as trusted is a security boundary failure.
Restate the goal of “Repository Design Decisions and Anti Patterns” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: credentials/session → token → verification → trusted identity → protected operation. 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.
const token = readBearerToken(request);
const claims = await verifier.verify(token);
request.user = {
id: claims.sub,
email: claims.email,
};Do 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.
Inspect whether a token exists, whether it is expired, which issuer/audience signed it, and what the API verifier expects.
Trust only verified server claims; never repair identity by accepting a client-sent user id.
Without copying the final source, create a second small scenario that applies “Repository Design Decisions and Anti Patterns” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Create web and API workspaces without copying node_modules between them.
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.