| name | review-architecture |
| description | Architecture-focused monorepo review. USE WHEN: user runs /review-architecture or explicitly asks for this review. DO NOT USE WHEN: implementing features or fixing bugs unless the user asked for a review.
|
| disable-model-invocation | true |
Review architecture
Run an architecture-focused review of the monorepo: layout, workspace dependencies, Turborepo task graph, app vs package boundaries, dependency direction, and module coupling/cohesion. Your reply must be a plan of suggested changes: concise, actionable, and structured-not only prose.
Invocation
Text after the slash command is additional scope/focus - narrow the review accordingly. If none given, use the default scope described below.
Best practices alignment
- Dependency direction - Apps depend on packages; packages must not depend on apps. No circular dependencies between workspaces.
- Single responsibility - Each package has one clear purpose (e.g.
@repo/dtos-common, @repo/enums-common, @repo/typescript-config).
- Public API surface - Packages expose a minimal, stable API via barrel exports; internal modules are not re-exported unless intentional.
- Turborepo - Task graph is acyclic; cache boundaries and
dependsOn are correct; no redundant or missing tasks.
- Root scripts - Single pnpm entry point for common operations; package scripts + turbo filters for scoped work; port allocation is documented and consistent.
Align with root AGENTS.md and app-level AGENTS.md for stated architecture and naming.
Deep technical review
Conduct an architecture-only review. Inspect the following and call out violations or improvements.
Monorepo layout and boundaries
- Artifacts: pnpm-workspace.yaml, root package.json, apps/ and packages/ directory structure.
- Checks: Workspace globs (
apps/*, packages/*) match actual layout. No app code under packages/ and no shared library code under apps/ except app-specific utilities. Clear naming: front-app (React + Vite frontend), worker-api (API worker), dtos-common / enums-common (shared contracts), typescript-config (TS configs only). Optional: worker-frontend as a second Vite app if present.
Workspace dependencies and dependency direction
- Artifacts: Each app and package package.json (dependencies and devDependencies), imports of
@repo/* across the repo.
- Checks: Apps list
@repo/dtos-common, @repo/enums-common, and/or @repo/typescript-config with workspace protocol (workspace:* or workspace:^) where appropriate. Packages do not depend on apps or on each other unless documented (e.g. typescript-config may be dev-only). Run (or reason about) pnpm why <package> to detect unnecessary or circular dependencies. No circular workspace dependencies.
Turborepo task graph and caching
- Artifacts: turbo.json, root and app package.json scripts.
- Checks: Turbo package tasks include
transit, check-types, types, types:check, build, dev, preview, deploy (no turbo lint/format — OXC is whole-repo outside Turborepo by design). check-types uses the transit-node pattern (dependsOn: ["transit"]), not ^check-types. build depends on ^build + check-types. global.inputs should stay lean (currently pnpm-workspace.yaml; pnpm 11 ignores non-auth project .npmrc settings) — do not expect OXC configs or a root tsconfig.json in the global hash (there is no root solution tsconfig; packages extend @repo/typescript-config). Package-level turbo.json tags every workspace for boundaries. No task cycles. Caching is beneficial (e.g. build cacheable, dev/deploy not cacheable).
Root scripts and port allocation
- Artifacts: Root package.json scripts, turbo.json, app/package package.json scripts under apps/ and packages/.
- Checks: Root pnpm install / pnpm dev / pnpm check / pnpm check-types / pnpm deploy behave as documented in AGENTS.md. Port allocation is consistent (e.g. 5174 for front-app, 8700 for worker-api) and documented. No duplicated orchestration that should live in root scripts.
Package public API and barrel exports
App-level structure
- Artifacts: Root AGENTS.md, apps/worker-api/AGENTS.md, apps/worker-api/src/ (routes, handlers), apps/front-app/src/ (React components, utils, enums).
- Checks: worker-api: clear separation routes → handlers/services; validation with shared Zod DTOs from
@repo/dtos-common; no business logic in route handlers beyond orchestration. front-app: UI and client-only logic in React; API calls over HTTP to worker-api. Alignment with AGENTS.md application structure.
Anti-patterns to flag
- Packages depending on apps or on each other in a cycle.
- Turborepo tasks that can run in parallel but are serialized unnecessarily, or cache keys that ignore critical inputs.
- Package scripts that duplicate root behavior or use inconsistent env (e.g. different Node version).
- Barrel exports that re-export everything (e.g. wildcard re-exports from internals), making the public API unclear.
- Apps importing from package paths that are not part of the package’s declared exports (brittle, may break on publish).
Steps
- Gather scope - Full monorepo or specific area (e.g. only packages, only Turborepo). If scope is unclear, default to full architecture.
- Read conventions - Root AGENTS.md and app AGENTS.md for stated architecture, workspace layout, and port allocation.
- Inspect workspace and dependencies - Open pnpm-workspace.yaml, root and app/package package.json files; trace
@repo/* and cross-workspace dependencies; reason about or run cycle detection.
- Inspect Turborepo - Open turbo.json and script definitions; verify task graph and cache configuration.
- Inspect root scripts - Root package.json scripts and turbo.json; package scripts; verify tasks and port usage.
- Inspect package APIs - packages/dtos-common, packages/enums-common, and packages/typescript-config entry points and exports; ensure minimal, stable public API.
- Review app structure - worker-api layers (routes, handlers); front-app React tree and boundaries with worker-api; alignment with AGENTS.md.
- Compose plan - Critical / Improvements / Optional; each item: what, where, why. If a sub-area has no findings, say so in one line.
Checklist
Context usage
- Use
@file for package.json, turbo.json, and AGENTS.md when reviewing structure.
- Use
@code for specific dependency or export snippets when suggesting changes.
- Use
@git when reviewing recent architectural changes in commits or PRs.
If context is insufficient, suggest which files or @ references to add.
Review checklist
- Correctness: Dependency direction and task graph are logically correct; no cycles.
- Conventions: Matches AGENTS.md layout and naming (apps vs packages, port allocation).
- Quality: Clear boundaries, minimal and stable package APIs, reproducible builds via pnpm/turbo.
- Actionability: Every suggestion is implementable (e.g. "move X to package Y", "add task Z to turbo.json").
- Trade-offs: If a suggestion has trade-offs (e.g. splitting a package), state them briefly.
- Scope: Limit to architecture; call out config, security, or performance as separate follow-ups if needed.
Output format
Respond with a plan only (no implementation unless the user asks):
- Critical – Architecture violations (circular deps, wrong dependency direction, broken task graph).
- Improvements – Worthwhile changes (clearer boundaries, better task deps, cleaner package API).
- Optional – Nice-to-haves (docs, minor renames). Prefix with Nit: for non-blocking polish.
For each item: what to change, where (file/area), and why. Keep items short and scannable. If a sub-area has no findings, state it in one line (e.g. "Turborepo task graph: no issues identified").
