ROUTING ARCHITECTURE
COMPLETE SYSTEM REFERENCE
Living documentation of the FYT Design System's routing architecture, content rendering system, and page type taxonomy. This document maps every route, component, and content flow in the application.
SYSTEM OVERVIEW
Architecture at a glance
REACT ROUTER V7
Client-side routing with BrowserRouter, Routes, and Route components
Single Router instance in App.tsx wraps entire application
LAZY LOADING
Non-critical pages lazy loaded with React.lazy() for code splitting
Reduces initial bundle size, improves performance
YAML-BASED CONTENT
Content stored in YAML files, processed by Go CLI, rendered by React
Single source of truth in content/ directory
HYBRID RENDERING
Mix of hardcoded React components and YAML-driven pages
Transitioning from React to YAML for maintainability
COMPLETE ROUTE MAP
Every route in the application
HARDCODED REACT
ROOT & CORE PAGES
Primary navigation routes
/
Home.tsx - Landing page
/about
About.tsx - About FYT
/components
Components.tsx - Component library
/build
Build.tsx - Build system docs
/changelog
Changelog.tsx - YAML-based
HYBRID SYSTEM
BLOG ROUTES
Blog listing and individual posts
/blog
Blog.tsx - Post listing
/blog/:slug
BlogPostPage.tsx - Individual post
Content Source
content/blog/*.yaml
YAML-DRIVEN
DOCUMENTATION ROUTES
Documentation index and sub-pages
/docs
Documentation.tsx - Hardcoded index
/docs/*
DocPage.tsx - YAML renderer
Registered Pages
14 pages in docPages mapping
MIXED
UTILITY ROUTES
Testing and data pages
/claims-and-data
ClaimsAndData.tsx - Hardcoded
/accessibility
AccessibilityTest.tsx
/print-test
PrintTest.tsx
/contact
Placeholder div
DOCUMENTATION PAGES REGISTRY
All pages registered in DocPage.tsx
5 PAGES
TECHNICAL DOCUMENTATION
Implementation and architecture docs
technical/print-optimization
Print optimization guide
technical/performance-optimization
Performance tuning
technical/footer-component
Footer implementation
todo
Project TODO list
contributing
Contribution guidelines
2 PAGES
AUDITS & REPORTS
Performance and claims audits
audits/performance-audit
Lighthouse audit results
audits/claims-audit
Marketing claims validation
7 PAGES
CONTENT MANAGEMENT
CLI and content system docs
content-management/overview
System overview
content-management/cli-reference
CLI commands
content-management/creating-content
Creating new content
content-management/editing-content
Editing existing content
content-management/styling-variants
Styling and variants
content-management/validation
Content validation
content-management/deleting-content
Deleting content
PAGE TYPE TAXONOMY
All available section types and their use cases
CONTENT TYPE
Markdown-heavy content with HybridContent renderer. Supports code blocks, tables, lists, quotes.
Status: TEMPORARY - Use for quick imports only, migrate to structured types
FEATURES TYPE
Grid of feature cards with title, description, detail, icon, and variant. Perfect for feature lists.
Status: PRODUCTION - Primary structured type for feature documentation
USE-CASES TYPE
Cards with specs arrays and alert badges. Ideal for technical specifications and status indicators.
Status: PRODUCTION - Use for technical docs with detailed specs
GETTING-STARTED TYPE
Numbered step cards for sequential processes. Shows step number, title, description.
Status: PRODUCTION - Use for tutorials and step-by-step guides
DOCUMENTATION-SECTION TYPE
Grid of linked items with title, description, href, icon. Used for doc index pages.
Status: DEFINED - Not yet rendered in DocPage.tsx
HERO TYPE
Page hero with title, subtitle, lead_text, CTA buttons, alerts. Rendered at page top.
Status: PRODUCTION - Standard for all YAML pages
CONTENT RENDERING FLOW
How content flows from YAML to rendered page
YAML AUTHORING
Content created in content/pages/*.yaml following page.schema.json structure
GO CLI BUILD
fyt build processes YAML, validates schema, generates dist/content.json
CONTENT LOADING
React imports YAML files directly via esbuild YAML plugin or loads content.json
ROUTE MATCHING
React Router matches URL to Route component (DocPage, Home, Blog, etc.)
PAGE COMPONENT
Component receives YAML data, extracts meta, hero, sections, styling
SECTION RENDERING
Component maps over sections array, renders based on type (features, use-cases, etc.)
BROWSER DISPLAY
Final HTML rendered with Tailwind CSS classes, brutal aesthetic applied
CURRENT STATE ANALYSIS
What works, what needs improvement
PRODUCTION READY
WORKING WELL
Solid foundation in place
TODO & Contributing
✅ Fully structured YAML
Route Registration
✅ 15 doc pages registered
Page Types
✅ 5 types in production
DocPage Renderer
✅ ALL types supported
Build System
✅ Go CLI working
Schema Validation
✅ JSON schema defined
LOWER PRIORITY
NEEDS IMPROVEMENT
Technical debt and gaps
Markdown Usage
⚠️ 12 pages still use content type
Documentation.tsx
⚠️ Hardcoded, should use YAML
Footer Component
⚠️ .md file needs YAML conversion
Nested Router Error
⚠️ Dev server hot reload issue
HIGH PRIORITY
MIGRATION PRIORITIES
Pages to convert to structured YAML
Technical Docs
3 pages with markdown content
Content Management
7 pages with markdown content
Audits
2 pages with markdown content
Target
100% structured by v3.0
FUTURE WORK
ENHANCEMENT OPPORTUNITIES
New capabilities to add
Tabs Component
For multi-section content
Accordion Type
For collapsible sections
Timeline Type
For chronological content
Comparison Type
For side-by-side comparisons
Gallery Type
For image collections
DOCPAGE RENDERER CAPABILITIES
Complete section type support (Patch 1 - COMPLETED)
CONTENT TYPE RENDERING
Renders markdown content with HybridContent component
Status: ✅ WORKING - Legacy support maintained
FEATURES TYPE RENDERING
Renders feature cards with icons, title, description, detail
Status: ✅ WORKING - Grid layout with variants
USE-CASES TYPE RENDERING
Renders cards with specs arrays and alert badges
Status: ✅ WORKING - Perfect for technical specs
GETTING-STARTED TYPE RENDERING
Renders numbered step cards for sequential processes
Status: ✅ WORKING - Great for tutorials
DOCUMENTATION-SECTION TYPE
Renders linked items grid for doc index pages
Status: ✅ WORKING - Clickable card navigation
COMPLETE COVERAGE
All section types from schema are now supported
Status: ✅ COMPLETE - No more limitations
IMPROVEMENT ACTION PLAN
5-patch roadmap - Patches 1-2 COMPLETE
ENHANCE DOCPAGE RENDERER
COMPLETED: Added rendering for features, use-cases, getting-started, documentation-section types. DocPage.tsx now handles all section types defined in schema.
ROUTE REGISTRATION AUDIT
COMPLETED: Verified all YAML pages registered in docPages mapping. Fixed missing testing.yaml. Removed broken footer-component link. 15 pages now registered.
MIGRATE TECHNICAL DOCS
OPTIONAL: Convert technical/print-optimization, technical/performance-optimization from markdown to structured types. Current markdown rendering works well.
MIGRATE CONTENT MANAGEMENT
OPTIONAL: Convert all 7 content-management pages from markdown to structured types. Use features and getting-started types for better structure.
DOCUMENTATION IMPROVEMENTS
FUTURE: Convert Documentation.tsx to YAML-based. Convert footer-component.md to YAML. Add more page types (tabs, accordion, timeline, comparison, gallery).
MAINTAINING THIS DOCUMENT
Keep architecture docs in sync with reality
UPDATE ON ROUTE CHANGES
When adding/removing routes in App.tsx, update the route map section
Keep route map comprehensive and accurate
UPDATE ON PAGE TYPE CHANGES
When adding new section types to schema, document them in taxonomy section
Include status, use cases, and examples
UPDATE ON MIGRATIONS
When converting pages from markdown to structured, update current state analysis
Track progress toward 100% structured content
QUARTERLY REVIEW
Review this document quarterly to ensure accuracy and completeness
Architecture evolves - docs must keep pace