SEO Architecture

Document: 22-seo-architecture.md
Version: 1.0.0

Purpose

This document defines the SEO architecture and implementation standards used across all Rundown projects.

Search Engine Optimization (SEO) is a fundamental architectural consideration that influences how content is structured, rendered, and discovered. Rather than being treated as a post-development task, SEO should be integrated throughout the development process.

This document establishes the architectural principles that ensure every Rundown application is discoverable, performant, and search-engine friendly.

SEO Philosophy

SEO is an architectural responsibility.

Every decision related to routing, content modelling, rendering, metadata, and performance contributes to search visibility.

SEO should be built into the application rather than applied after development is complete.

Responsibilities

The SEO layer owns:

Metadata
Structured data
URL strategy
Sitemap generation
robots.txt
Canonical URLs
Social sharing metadata
Search engine discoverability

Non-Responsibilities

SEO should not own:

Marketing strategy
Keyword research
Content writing
Advertising
Analytics

SEO architecture enables discoverability but does not replace content strategy.

Rendering Strategy

Rendering should prioritize search engine accessibility.

Preferred rendering strategies:

Static Site Generation (SSG) for evergreen content
Server-Side Rendering (SSR) for dynamic content
Server Components where appropriate

Avoid unnecessary client-side rendering for content intended to be indexed.

Metadata

Every indexable page should include:

Title
Meta description
Canonical URL
Open Graph metadata
Twitter Card metadata (or equivalent platform metadata)
Favicon
Theme color (where applicable)

Metadata should be generated dynamically whenever content is managed through Payload CMS.

URL Structure

URLs should be:

Human-readable
Stable
Descriptive
Lowercase
Hyphenated

Examples:

/services/web-development

/blog/building-scalable-websites

/portfolio/magtik-bharat

Avoid:

/page?id=42

/blog/post123

Structured Data

Where appropriate, applications should implement structured data using Schema.org.

Examples include:

Organization
Article
Product
FAQ
Breadcrumb
Local Business

Structured data should reflect the actual content presented to users.

Sitemap

Every production application should generate an XML sitemap automatically.

The sitemap should:

Include indexable pages.
Exclude private routes.
Update automatically when content changes.

robots.txt

Every application should provide a robots.txt file.

Typical responsibilities include:

Allowing search engine crawling.
Blocking administrative routes.
Referencing the XML sitemap.

Canonical URLs

Canonical URLs should be defined for every indexable page.

Canonical URLs help prevent duplicate content and improve search engine indexing.

Images

Images should:

Use descriptive filenames.
Include meaningful alt text.
Be optimized for performance.
Use modern formats such as WebP or AVIF where appropriate.

Decorative images should use empty alt attributes.

Internal Linking

Applications should encourage logical internal linking.

Examples:

Related blog posts
Related services
Related portfolio projects
Product categories

Internal links improve navigation and content discoverability.

Internationalization

Projects supporting multiple languages should:

Use localized URLs.
Implement hreflang where appropriate.
Maintain language-specific metadata.

Internationalization should be planned during architecture rather than added later.

Performance

SEO depends on performance.

Applications should optimize:

Core Web Vitals
Image delivery
JavaScript execution
Rendering speed
Cumulative Layout Shift (CLS)
Largest Contentful Paint (LCP)

Performance improvements directly support search visibility.

Monitoring

SEO should be monitored using tools such as:

Google Search Console
Bing Webmaster Tools (when applicable)
Analytics platforms

Monitoring should identify indexing issues, crawl errors, and opportunities for improvement.

Engineering Decision

SEO by Architecture

Status: Accepted

Decision

SEO considerations are integrated into the architecture of every Rundown application rather than implemented as a final development task.

Reasoning

Architectural SEO:

Produces more consistent results.
Reduces technical debt.
Simplifies maintenance.
Improves long-term search visibility.
Aligns naturally with Next.js rendering capabilities.

SEO Checklist

Before deployment, verify:

Metadata is complete.
Canonical URLs are configured.
Sitemap is generated.
robots.txt is present.
Structured data is implemented where appropriate.
Images include alt text.
URLs follow Rundown standards.
Internal links are functioning.
Performance objectives have been reviewed.

Summary

SEO is an architectural concern that influences how applications are structured, rendered, and discovered.

By embedding SEO principles into the foundation of every Rundown project, applications remain discoverable, maintainable, and capable of achieving strong organic search performance without requiring significant post-development adjustments.

ADR-001: Repository Structure