Phase 1 - Content & Data Architecture

Done

Overview

• Tier: Foundation (Phase 1 of 12)
• Scope: Essential — every project completes this phase (scope labels follow ADR-033)
• Duration: 1-2 days
• Dependencies: Phase 0 (Foundation) completed
• Deliverables: Content schema, TypeScript types, URL strategy, content fixtures
• Code examples: Phase 1 - Code Examples

Entry Criteria

• Astro project initialized
• TypeScript configured in strict mode
• Development environment functional
• Content requirements gathered

Implementation Steps

Step	Task	Scope	Notes
1.01	Inventory content types	Essential	List all content needs
1.02	Design URL structure	Essential	SEO-friendly paths
1.03	Create content collections	Essential	Define in src/content.config.ts
1.04	Define collection schemas	Essential	Zod schemas
1.05	Add draft mechanism	Essential	Boolean field
1.06	Generate TypeScript types	Essential	Auto from schemas
1.07	Create slug utilities	Essential	Consistent URL generation
1.08	Set up MDX components	Essential	Custom elements
1.09	Create content fixtures	Essential	One per type
1.10	Add frontmatter validation	Essential	astro check
1.11	Document content model	Essential	Content model changelog (see code examples)
1.12	Create content guidelines	Essential	For authors

Common Pitfalls

1. Overly Complex Schemas: Starting with too many fields

   • Solution: Add fields as needed, start minimal

2. Missing Draft Field: Accidentally publishing unfinished content

   • Solution: Make draft:true the default, explicitly set to false

3. Inconsistent Slugs: URLs that change breaking links

   • Solution: Generate slugs once, store in frontmatter

4. Type Mismatches: Schema doesn’t match actual content

   • Solution: Use fixtures to test schemas early

Exit Criteria

• All content types identified and documented
• URL structure defined and consistent
• Content collections configured with schemas
• TypeScript types generating correctly
• Draft mechanism implemented and tested
• Slug generation utilities working
• MDX components configured
• At least one fixture per content type
• Validation passing with astro check
• Content model changelog created
• Author guidelines documented

Rollback Strategy

If content architecture needs changes:

1. Schema Changes:

   # Illustrative — the starter ships no migration script. Project scripts live
   # in scripts/src/*.ts and run with tsx (ADR-052), so one would look like:
   pnpm exec tsx scripts/src/migrate-content.ts --from v1 --to v2

2. URL Structure Changes:

   • Set up redirects in astro.config.mjs
   • Update all internal links
   • Submit new sitemap

3. Collection Rename:

   • Move files to new location
   • Update imports
   • Clear .astro cache

AI Assistant Notes

Key Files to Reference

• src/content.config.ts - Collection schemas (Content Layer)
• src/utils/url-utils.ts - URL patterns
• src/content/*/ - Content examples
• Content model changelog

Common Prompts for This Phase

• “Create Astro content collection schema for [type]”
• “Generate TypeScript types from content schema”
• “Set up MDX components for rich content”
• “Create URL structure for SEO”

Context Requirements

• Types of content (blog, portfolio, etc.)
• URL preferences (with/without dates)
• Required metadata fields
• Future content plans

References

• Astro Content Collections Documentation
• Zod Schema Validation
• SEO-Friendly URL Structure Best Practices

---

Return to Phase 0: Foundation Decisions | Proceed to Phase 2: Design System & Tokens