Architecture Overview

Architecture Overview

This page explains the key architectural concepts and design decisions that shape nodecode-docs-astro.

Core Technologies

Astro

Astro is a modern static site generator that ships zero JavaScript by default. It provides:

• Island Architecture: Components are hydrated independently for optimal performance
• Content Collections API: Type-safe content with schema validation
• Multi-framework Support: Use React, Vue, Svelte, or just HTML
• Optimized Output: Minimal JavaScript, optimized CSS, fast page loads

Starlight

Starlight is Astro’s official documentation theme, providing:

• Built-in Components: Search, navigation, table of contents, dark mode
• Accessibility First: WCAG AA compliant out of the box
• i18n Support: Multi-language documentation support
• Customizable Theme: CSS custom properties for easy styling

Content Collections

Content Collections provide type-safe content management:

// src/content/config.ts defines the schema
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    schema: docsSchema()
  }),
};

Benefits:

• TypeScript autocompletion for frontmatter fields
• Build-time validation catches errors early
• Type-safe queries with getCollection() and getEntry()
• IDE support for content authoring

Information Architecture

The documentation is organized into 5 main sections:

1. Guides

Purpose: How-to instructions for common tasks

Characteristics:

• Task-oriented
• Step-by-step format
• Practical examples
• Quick to complete

2. Reference

Purpose: Technical specifications and API documentation

Characteristics:

• Comprehensive coverage
• Organized by topic
• Searchable details
• Accurate and up-to-date

3. Tutorials

Purpose: In-depth learning experiences

Characteristics:

• Hands-on exercises
• Progressive difficulty
• Complete workflows
• Learning objectives

4. Concepts

Purpose: Explanations of key ideas and architecture

Characteristics:

• Educational focus
• Conceptual understanding
• Big-picture thinking
• Context and reasoning

5. Troubleshooting

Purpose: Solutions to common problems

Characteristics:

• Problem-solution format
• Searchable issues
• Quick fixes
• Diagnostic steps

Design System

The site uses a monochrome design system built on:

• Color Tokens: Pure black background (#000), white text (#fff), grayscale accents
• Spacing Tokens: 8px grid system (—space-1 through —space-12)
• Typography Tokens: System font stacks, modular scale (1.25 ratio)
• Accessibility: 21:1 contrast ratio exceeding WCAG AA standards

All design tokens are defined in src/styles/tokens.css and applied via src/styles/theme.css.

Build Pipeline

The build process follows these steps:

1. Content Sync: Astro reads and validates all content files
2. Type Generation: TypeScript types generated from Content Collections schema
3. Component Rendering: Astro components rendered to static HTML
4. Asset Optimization: Images optimized, CSS minified, JS bundled
5. Static Output: Final static files written to dist/ directory

Performance Targets:

• Build time: < 5 seconds for typical site
• Page load time: < 1 second on 3G
• Lighthouse score: > 95 across all metrics

Development Workflow

The recommended development workflow:

1. Start Dev Server: bun run dev for hot module reloading
2. Edit Content: Markdown/MDX files with instant preview
3. Type Check: bun run check for validation
4. Build: bun run build for production output
5. Preview: bun run preview to test production build
6. Deploy: Push to Cloudflare Pages (or other static host)

Extensibility

The architecture supports extensions through:

• Custom Components: Add Astro/React/Vue components in src/components/
• MDX Integration: Use components directly in Markdown
• Schema Extensions: Extend frontmatter schema for custom fields
• Theme Overrides: Customize Starlight theme via CSS custom properties
• Integration API: Add Astro integrations for additional functionality

Performance Characteristics

Key performance metrics:

• First Contentful Paint (FCP): < 1.0s
• Largest Contentful Paint (LCP): < 2.5s
• Cumulative Layout Shift (CLS): < 0.1
• Time to Interactive (TTI): < 3.0s

Achieved through:

• Static HTML generation (no client-side rendering)
• Minimal JavaScript (only for interactive features)
• Optimized assets (images, fonts, CSS)
• Efficient caching strategies

Security Considerations

Security features include:

• Static Output: No server-side code execution
• Content Security Policy: Strict CSP headers (when deployed)
• No Dynamic Data: All content generated at build time
• HTTPS: Enforced via deployment platform
• Dependency Updates: Regular security audits and updates

Future Architecture

Planned architectural improvements:

• Versioned documentation support
• Advanced search with filters
• Interactive playground for code examples
• API reference auto-generation
• Multi-site content sharing

---

This architecture provides a solid foundation for a high-performance, maintainable, and scalable documentation site.