Review Architecture

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

• Artifacts: packages/dtos-common/src/ (barrel and subpaths), packages/dtos-common/package.json, packages/enums-common/src/index.ts, packages/enums-common/package.json, packages/typescript-config/ (exports in package.json if any).
• Checks: @repo/dtos-common and @repo/enums-common expose only what consumers need; no leaking of internal paths. @repo/typescript-config exposes config files only; no runtime code. Package main/exports point to stable entry points. No deep imports that bypass declared exports unless intentional and documented.

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

1. Gather scope - Full monorepo or specific area (e.g. only packages, only Turborepo). If scope is unclear, default to full architecture.
2. Read conventions - Root AGENTS.md and app AGENTS.md for stated architecture, workspace layout, and port allocation.
3. 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.
4. Inspect Turborepo - Open turbo.json and script definitions; verify task graph and cache configuration.
5. Inspect root scripts - Root package.json scripts and turbo.json; package scripts; verify tasks and port usage.
6. Inspect package APIs - packages/dtos-common, packages/enums-common, and packages/typescript-config entry points and exports; ensure minimal, stable public API.
7. Review app structure - worker-api layers (routes, handlers); front-app React tree and boundaries with worker-api; alignment with AGENTS.md.
8. Compose plan - Critical / Improvements / Optional; each item: what, where, why. If a sub-area has no findings, say so in one line.

Checklist

• Scope clear (full monorepo or specified area)
• Root and app AGENTS.md consulted for architecture
• pnpm-workspace.yaml and all package.json dependency lists reviewed
• Circular or reverse dependency direction checked
• turbo.json task graph and cache deps reviewed
• Root package.json scripts and turbo tasks reviewed; ports consistent
• Package public APIs (dtos-common, enums-common, typescript-config) reviewed
• worker-api and front-app internal structure reviewed
• Plan structured as Critical / Improvements / Optional with what/where/why

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):

1. Critical – Architecture violations (circular deps, wrong dependency direction, broken task graph).
2. Improvements – Worthwhile changes (clearer boundaries, better task deps, cleaner package API).
3. 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").