name	site-architecture
description	Code-generation skill for planning and implementing Career Hub page hierarchy, navigation, URL structure, and internal linking in the repo.
metadata	{"family":"seo","owner":"seo + engineering","last_reviewed":"2026-04-30T00:00:00.000Z","version":"1.0.0"}

Site Architecture (Career Hub)

This is a code-generation skill. Use it only when the outcome is routing, navigation, or internal-linking implementation work.

Audit and maintain the Career Hub's information architecture: page hierarchy, navigation, URL patterns, internal linking, and hub-and-spoke relationships.

Read nextjs-app/docs/BRAND.md for editorial standards. Read nextjs-app/docs/SEO.md for URL patterns and technical SEO specs.

When to Use

Planning new page types or routes
Restructuring navigation (header menu, footer)
Auditing internal linking completeness
Checking for orphan pages
Validating hub-and-spoke relationships
After deploying new programmatic page types

Current Site Architecture

Career Hub (/)
├── Roles Pillar (/career-hub/roles)
│   └── Role Detail (/career-hub/roles/[slug])
│       ├── How to Become (/how-to-become/[slug])
│       ├── Interview Questions (/interview-questions/[slug])
│       ├── Resume Examples (/career-hub/resume-examples/[slug])
│       ├── Salary by City (/career-hub/salary/[slug])
│       └── City x Role (/career-hub/cities/[city]/[role])
├── Cities Pillar (/career-hub/cities)
│   └── City Detail (/career-hub/cities/[slug])
│       └── City x Role (/career-hub/cities/[city]/[role])
├── Guides Pillar (/career-hub/guides)
│   └── Guide Article (/career-hub/guides/[slug])
├── Financial Tips (/career-hub/financial-tips)
│   └── Article (/career-hub/financial-tips/[slug])
├── Tools (/career-hub/tools)
│   └── Tool Page (/career-hub/tools/[slug])
├── Persona Hubs (/career-hub/for)
│   └── Persona Page (/career-hub/for/[slug])
├── State Pages
│   ├── Paycheck Calculator (/paycheck-calculator/[state])
│   └── Unemployment Benefits (/unemployment-benefits/[state])
├── Certifications (/certifications/[slug])
└── Seasonal Pages
    ├── Summer Jobs (/career-hub/summer-jobs-2026)
    └── Holiday Jobs (/career-hub/holiday-jobs-2026)

The 3-Click Rule

Every important page must be reachable within 3 clicks from the Career Hub homepage.

Level	Click 1	Click 2	Click 3
Role detail	Career Hub > Roles > Bartender	3 clicks	OK
City-Role	Career Hub > Cities > Philadelphia > Bartender	4 clicks	Add direct links from pillar pages
How-to-Become	Career Hub > Roles > Bartender > How to Become	4 clicks	Add spoke links on pillar page cards
Tool	Career Hub > Career Tools menu > Pay Calculator	2 clicks	OK
Guide article	Career Hub > Guides > Article	3 clicks	OK

Audit action: Count clicks from homepage to each page type. Flag any page type requiring 4+ clicks.

Internal Linking Audit

Link Requirements by Page Type

Page Type	Min Outgoing	Min Incoming	Must Link To
Pillar page (roles, cities)	10+	5+ (from hub, header nav, footer)	Every spoke page in category
Role detail	5+	3+ (from pillar, city-role, related roles)	How-to-become, interview, resume, salary (if exist)
City detail	5+	2+ (from pillar, nearby cities)	All city-role pages, tools (cost of living, pay calc)
City-Role	5+	2+ (from city page, role page)	City page, role page, related city-roles, tools
Guide article	3+	2+ (from hub, related articles)	Related articles, relevant tools
Tool page	2+	3+ (from articles, role pages, city pages)	Related articles, app download

Audit Process

Run link matrix: For each page type, count outgoing and incoming internal links. Flag pages below thresholds.
Check for orphan pages: Run: rg "generateStaticParams" src/app/ --glob "*/page.tsx" -l For each dynamically generated page, verify at least one internal link points to it.
Verify hub-to-spoke links:
- Roles pillar links to ALL role detail pages (via cards)
- Role detail links to ALL available spoke pages (interview, how-to, resume, salary)
- Cities pillar links to ALL city detail pages
- City detail links to city-role pages for high-value cities
Check anchor text quality: Anchor text should be descriptive. Flag "click here", "read more", "learn more" used as anchor text.
Verify cross-section links:
- Role pages link to relevant city-role pages
- Guide articles link to relevant tools
- Tool pages link to relevant guides
- City pages link to relevant role pages

Components That Generate Links

Component	What It Links	Where Used
`InternalLinkHub`	Contextual links based on page type	All pages (footer variant)
`RelatedContent`	Related roles, locations, tools, guides	Role detail pages
`Breadcrumbs`	Parent hierarchy	All pages
`CTASection`	App download	All pages (bottom)
Header nav	Pillar pages, tools	All pages
Footer	Key pages across all sections	All pages

URL Structure Rules

Rule	Requirement
Readable by humans	`/career-hub/roles/bartender` not `/r/123`
Hyphens, not underscores	`/new-york` not `/new_york`
Lowercase always	`/bartender` not `/Bartender`
Reflect hierarchy	URL path matches site structure
Consistent trailing slash	No trailing slash (Next.js default)
Short but descriptive	Max 5-6 path segments

URL Consistency Audit

Run: rg "href=" src/app/ --glob "*.tsx" | grep -oP '"/[^"]*"' | sort -u Flag any URLs that violate the rules above or create inconsistencies.

Navigation Design

Header Navigation (4 pillars)

Current: Explore Jobs, Application Toolkit, Career Guides, Career Tools

Rules:

4-7 items max in primary nav
CTA button ("Download App") rightmost
Logo links to Career Hub homepage
Each pillar has a dropdown with categorized links

Breadcrumb Rules

Every page has breadcrumbs
Breadcrumb trail mirrors URL hierarchy
Each segment is clickable except current page
BreadcrumbSchema JSON-LD on every page

Output Format

Architecture Audit Report

## Site Architecture Audit

### 3-Click Rule Violations
| Page Type | Current Clicks | Recommended Fix |

### Orphan Pages
| Page | Why Orphaned | Fix |

### Internal Link Gaps
| Page | Outgoing | Incoming | Missing Links |

### URL Inconsistencies
| URL | Issue | Fix |

### Navigation Recommendations
- [specific changes]

Related Skills

site-growth — SEO health audit (technical, schema, freshness)
page-cro — Page conversion optimization
content-review — Content quality scoring

name	site-architecture
description	Code-generation skill for planning and implementing Career Hub page hierarchy, navigation, URL structure, and internal linking in the repo.
metadata	{"family":"seo","owner":"seo + engineering","last_reviewed":"2026-04-30T00:00:00.000Z","version":"1.0.0"}