30x-seo-architecture

Site Architecture

[PROTOCOL]: Update this header on changes, then check CLAUDE.md

You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.

Before Planning

Check for product marketing context first: If .agents/product-marketing-context.md exists (or .claude/product-marketing-context.md in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

1. Business Context

• What does the company do?
• Who are the primary audiences?
• What are the top 3 goals for the site? (conversions, SEO traffic, education, support)

2. Current State

• New site or restructuring an existing one?
• If restructuring: what's broken? (high bounce, poor SEO, users can't find things)
• Existing URLs that must be preserved (for redirects)?

3. Site Type

• SaaS marketing site
• Content/blog site
• E-commerce
• Documentation
• Hybrid (SaaS + content)
• Small business / local

4. Content Inventory

• How many pages exist or are planned?
• What are the most important pages? (by traffic, conversions, or business value)
• Any planned sections or expansions?

Site Types and Starting Points

| Site Type | Typical Depth | Key Sections | URL Pattern | |-----------|--------------|--------------|-------------| | SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | /features/name, /blog/slug | | Content/blog | 2-3 levels | Home, Blog, Categories, About | /blog/slug, /category/slug | | E-commerce | 3-4 levels | Home, Categories, Products, Cart | /category/subcategory/product | | Documentation | 3-4 levels | Home, Guides, API Reference | /docs/section/page | | Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | /product/feature, /blog/slug | | Small business | 1-2 levels | Home, Services, About, Contact | /services/name |

For full page hierarchy templates: See [references/site-type-templates.md](references/site-type-templates.md)

Page Hierarchy Design

The 3-Click Rule

Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.

Flat vs Deep

| Approach | Best For | Tradeoff | |----------|----------|----------| | Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale | | Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability | | Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |

Rule of thumb: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.

Hierarchy Levels

| Level | What It Is | Example | |-------|-----------|---------| | L0 | Homepage | / | | L1 | Primary sections | /features, /blog, /pricing | | L2 | Section pages | /features/analytics, /blog/seo-guide | | L3+ | Detail pages | /docs/api/authentication |

ASCII Tree Format

Use this format for page hierarchies:

Homepage (/)
├── Features (/features)
│   ├── Analytics (/features/analytics)
│   ├── Automation (/features/automation)
│   └── Integrations (/features/integrations)
├── Pricing (/pricing)
├── Blog (/blog)
│   ├── [Category: SEO] (/blog/category/seo)
│   └── [Category: CRO] (/blog/category/cro)
├── Resources (/resources)
│   ├── Case Studies (/resources/case-studies)
│   └── Templates (/resources/templates)
├── Docs (/docs)
│   ├── Getting Started (/docs/getting-started)
│   └── API Reference (/docs/api)
├── About (/about)
│   └── Careers (/about/careers)
└── Contact (/contact)

When to use ASCII vs Mermaid:

• ASCII: quick hierarchy drafts, text-only contexts, simple structures
• Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns

Navigation Design

Navigation Types

| Nav Type | Purpose | Placement | |----------|---------|-----------| | Header nav | Primary navigation, always visible | Top of every page | | Dropdown menus | Organize sub-pages under parent | Expands from header items | | Footer nav | Secondary links, legal, sitemap | Bottom of every page | | Sidebar nav | Section navigation (docs, blog) | Left side within a section | | Breadcrumbs | Show current location in hierarchy | Below header, above content | | Contextual links | Related content, next steps | Within page content |

Header Navigation Rules

• 4-7 items max in the primary nav (more causes decision paralysis)
• CTA button goes rightmost (e.g., "Start Free Trial," "Get Started")
• Logo links to homepage (left side)
• Order by priority: most important/visited pages first
• If you have a mega menu, limit to 3-4 columns

Footer Organization

Group footer links into columns:

• Product: Features, Pricing, Integrations, Changelog
• Resources: Blog, Case Studies, Templates, Docs
• Company: About, Careers, Contact, Press
• Legal: Privacy, Terms, Security

Breadcrumb Format

Home > Features > Analytics
Home > Blog > SEO Category > Post Title

Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.

For detailed navigation patterns: See [references/navigation-patterns.md](references/navigation-patterns.md)

URL Structure

Design Principles

1. Readable by humans — /features/analytics not /f/a123
2. Hyphens, not underscores — /blog/seo-guide not /blog/seo_guide
3. Reflect the hierarchy — URL path should match site structure
4. Consistent trailing slash policy — pick one (with or without) and enforce it
5. Lowercase always — /About should redirect to /about
6. Short but descriptive — /blog/how-to-improve-landing-page-conversion-rates is too long; /blog/landing-page-conversions is better

URL Patterns by Page Type

| Page Type | Pattern | Example | |-----------|---------|---------| | Homepage | / | example.com | | Feature page | /features/{name} | /features/analytics | | Pricing | /pricing | /pricing | | Blog post | /blog/{slug} | /blog/seo-guide | | Blog category | /blog/category/{slug} | /blog/category/seo | | Case study | /customers/{slug} | /customers/acme-corp | | Documentation | /docs/{section}/{page} | /docs/api/authentication | | Legal | /{page} | /privacy, /terms | | Landing page | /{slug} or /lp/{slug} | /free-trial, /lp/webinar | | Comparison | /compare/{competitor} or /vs/{competitor} | /compare/competitor-name | | Integration | /integrations/{name} | /integrations/slack | | Template | /templates/{slug} | /templates/marketing-plan |

Common Mistakes

• Dates in blog URLs — /blog/2024/01/15/post-title adds no value and makes URLs long. Use /blog/post-title.
• Over-nesting — /products/category/subcategory/item/detail is too deep. Flatten where possible.
• Changing URLs without redirects — Every old URL must 301 redirect to its new URL. No exceptions.
• IDs in URLs — /product/12345 is not human-readable. Use slugs.
• Query parameters for content — /blog?id=123 should be /blog/post-title.
• Inconsistent patterns — Don't mix /features/analytics and /product/automation. Pick one parent.

Breadcrumb-URL Alignment

The breadcrumb trail should mirror the URL path:

| URL | Breadcrumb | |-----|-----------| | /features/analytics | Home > Features > Analytics | | /blog/seo-guide | Home > Blog > SEO Guide | | /docs/api/auth | Home > Docs > API > Authentication |

Visual Sitemap Output (Mermaid)

Use Mermaid graph TD for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.

Basic Hierarchy

graph TD