repo-architecture

name	repo-architecture
description	Code-generation skill. Use only when a task touches repo structure, file placement, route boundaries, or where new code belongs in this Next.js app.
metadata	{"family":"code","owner":"engineering","last_reviewed":"2026-04-30T00:00:00.000Z","version":"1.0.0"}

Repo Architecture

This is a code-generation skill. Use it only for implementation placement and architecture decisions.

Use When

• creating a new route or feature
• deciding where a file should live
• moving code
• reviewing whether generated code matches repo structure

Core Rules

• Keep src/app thin.
• Put feature-owned code in src/features/<feature>.
• Use src/shared only for cross-feature infrastructure.
• Use src/lib only for low-level infrastructure/utilities.
• Use src/components/ui for primitives.
• Use src/components/common only for truly generic cross-feature helpers.

Dependency Direction

src/app -> src/features -> src/shared -> src/lib

Generate new code in that direction.

Put Code Here

src/app

Allowed:

• page.tsx
• layout.tsx
• error.tsx
• not-found.tsx
• robots.ts
• route handlers
• metadata / generateMetadata
• generateStaticParams

Not allowed as default:

• large page composition
• new feature helpers
• feature datasets

src/features

Default home for:

• page composition
• feature shells
• sections
• clients
• feature-local pure business logic such as logic.ts, helpers.ts, or services.ts
• feature data
• feature types
• feature schema wiring

src/shared

Current examples:

• src/shared/seo/JsonLd.tsx
• src/shared/sitemap/*

src/lib

Current examples:

• src/lib/seo/*
• src/lib/security/*
• src/lib/server/*
• src/lib/site/*
• src/lib/utils/*
• src/lib/calculators/*

Do not place new feature datasets here.

Logic Placement Rule

• If logic powers one feature or page family and does not need React, keep it in that feature as logic.ts, helpers.ts, or services.ts.
• Promote logic to src/lib only when it is truly cross-feature, low-level, and not owned by one domain.
• Do not leave calculator math or core business rules inside route files or bulky client components by default.

Current Reuse Hotspots

• src/features/career-hub/shared/*
• src/features/tools/shared/*
• src/features/roles/shared/*

These are active, not deprecated.

Forbidden Defaults

• new feature UI in src/components/career-hub/*
• new feature data in src/lib/data/*
• new feature support files in src/app/*

Output Standard

When you generate code, it should:

1. use a thin route file if a route is involved
2. place logic in the owning feature
3. reuse an existing shell/helper where possible
4. extract pure non-React logic into feature-local helpers instead of embedding it in JSX
5. avoid architecture-wide cleanup unrelated to the task