Architect URL Helper

Design, validate, and optimize URL architectures for web applications with focus on routing patterns, permalink structures, and RESTful conventions.

When to Use This Agent

Choose this agent when you need to:

• Design clean URL hierarchies for web applications, APIs, or CMS platforms following RESTful conventions and SEO-friendly patterns
• Refactor URL structures during site migrations with proper redirect mapping and backward compatibility
• Validate URL syntax, encoding correctness, path normalization, and query parameter handling

Consider alternatives when:

• You need to validate existing URLs for broken links rather than designing new structures
• Your concern is full API architecture design beyond URL routing

Quick Start

Configuration

Copy
name: architect-url-helper
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke architect-url-helper "Design URL architecture for a multi-tenant SaaS with API versioning"

Example Output

URL Architecture Proposal
==========================
TENANT ROUTING
- Web: https://{tenant}.app.example.com/dashboard
- API: https://api.example.com/v2/tenants/{tenant-id}

API ENDPOINTS
  /v2/tenants/{id}/users/          GET, POST
  /v2/tenants/{id}/users/{uid}     GET, PATCH, DELETE
  /v2/tenants/{id}/projects/       GET, POST

CONVENTIONS: lowercase kebab-case, plural nouns, UUID identifiers
MIGRATION: /api/users/* -> /v2/tenants/{ctx}/users/* [301]

Core Concepts

URL Architecture Principles

Aspect	Details
Path Hierarchy	Logical resource nesting, max 4 segments deep, collection/resource alternation
Naming	Lowercase, hyphen-separated slugs, plural nouns, no file extensions in routes
Identifiers	UUID v4 for public IDs, slugs for content, compound keys for nested resources
Versioning	URI path prefix (v1, v2), header-based, or query parameter strategies
Canonicalization	Trailing slash normalization, www consistency, protocol enforcement, case folding

URL Routing Architecture

+------------------+     +------------------+     +------------------+
|  Incoming URL    |---->|  Route Parser    |---->|  Pattern Match   |
|  DNS + TLS       |     |  Path Segments   |     |  Param Extract   |
+------------------+     +------------------+     +------------------+
        |                        |                        |
        v                        v                        v
+------------------+     +------------------+     +------------------+
|  Normalization   |     |  Auth & Tenant   |     |  Handler         |
|  Redirect Rules  |     |  Scope Validate  |     |  Dispatch        |
+------------------+     +------------------+     +------------------+

Configuration

Parameter	Type	Default	Description
url_style	string	"restful"	Pattern style: restful, hierarchical, flat, hybrid
slug_format	string	"kebab-case"	Slug convention: kebab-case, snake_case, camelCase
id_strategy	string	"uuid"	Identifier type: uuid, slug, numeric, nanoid
trailing_slash	string	"strip"	Handling: strip, require, or preserve
max_path_depth	integer	4	Maximum URL path segment depth

Best Practices

1. Design URLs as a User Interface - URLs appear in browser bars, shared messages, and printed materials. Prefer /products/wireless-headphones over /p?id=48291&cat=3 because readable URLs build trust and improve sharing.

2. Enforce Canonicalization Early - Choose a single canonical form for trailing slash, www prefix, protocol, and case from day one. Retroactive canonicalization after indexing multiple variants creates duplicate content headaches.

3. Version APIs in the Path - Path-based versioning (/v2/resources) provides superior developer experience through browser testability and documentation linking. Reserve header versioning for internal microservice communication.

4. Plan Redirect Maps Before Restructuring - Build complete old-to-new URL mappings before changes. Test with real traffic samples, keep chains under two hops, and monitor 404 rates for 90 days post-migration.

5. Separate Concerns Across Subdomains - Use api.example.com, app.example.com, cdn.example.com for independent scaling, deployment, and security policies without path collision.

Common Issues

1. URL Encoding Inconsistencies - Mixed encoding across application layers causes routing failures. Standardize encoding at the reverse proxy layer and validate all generated URLs against RFC 3986 before serving.

2. Identifier Enumeration Vulnerability - Sequential numeric IDs enable resource enumeration attacks. Switch to UUID v4 or nanoid for public-facing URLs, mapping through an opaque identifier layer at the API boundary.

3. Trailing Slash Redirect Loops - Conflicting rules between origin server and CDN create loops. Ensure normalization at exactly one layer and verify loop-free behavior for both /path and /path/ variants.