# Summit Painting & Handyman Services

> **Craftsmanship For Your Home**

The official website for Summit Painting & Handyman Services in Colorado Springs. Built with modern web technologies for performance, maintainability, and scalability.

## Technology Stack

- **Astro 5** - Static site generator with React islands
- **React 19** - Interactive components
- **TypeScript** - Type-safe development
- **Tailwind CSS 4** - Utility-first styling
- **MDX** - Markdown with embedded JSX
- **Cloudflare Pages** - Edge-deployed hosting
- **pnpm** - Fast, space-efficient package manager

## Quick Start

### Prerequisites

- Node.js 18+ and pnpm installed
- Git for version control

### Installation

```bash
# Clone the repository
git clone <repository-url>
cd summit-painting-handyman

# Install dependencies
pnpm install

# Copy environment template and configure
cp .env.example .env.local
# Edit .env.local with your configuration
```

### Development

```bash
# Start development server (http://localhost:3000)
pnpm dev

# Build for production
pnpm build

# Preview production build locally
pnpm preview
```

### Deployment

```bash
# Deploy to Cloudflare Pages
pnpm deploy
```

## Environment Variables

Create a `.env.local` file based on `.env.example`:

```bash
# Site Configuration
PUBLIC_SITE_URL=https://summitpaintingcolorado.com
PUBLIC_SITE_NAME=Summit Painting & Handyman

# Optional: Analytics, Contact Form, etc.
# Configure as needed for your services
```

## Project Structure

```
summit-painting-handyman/
├── src/
│   ├── assets/              # Images and media processed by Astro
│   ├── components/
│   │   ├── home/           # Homepage section components
│   │   │   ├── Hero.astro
│   │   │   ├── ServiceList.astro
│   │   │   ├── ServiceArea.astro
│   │   │   ├── WhyUs.astro
│   │   │   └── ExpertiseMosaic.astro
│   │   ├── site/           # Site-wide components
│   │   │   ├── Navigation.astro
│   │   │   ├── Footer.astro
│   │   │   └── GridOverlay.astro
│   │   └── ui/             # Reusable UI components
│   │       ├── Button.astro
│   │       ├── Container.astro
│   │       ├── Marquee.astro
│   │       └── SectionHeading.astro
│   ├── content/            # Content collections with schema validation
│   │   ├── blog/          # Blog posts (MDX)
│   │   ├── sections/      # Homepage sections
│   │   │   ├── hero.mdx
│   │   │   ├── experience.mdx
│   │   │   ├── skills.mdx
│   │   │   └── featured-project.mdx
│   │   └── pages/         # Page-specific content
│   │       └── contact.mdx
│   ├── layouts/            # Page layout templates
│   │   ├── BaseLayout.astro
│   │   └── BlogPost.astro
│   ├── pages/              # File-based routes
│   │   ├── index.astro
│   │   ├── contact.astro
│   │   ├── blog/
│   │   │   ├── index.astro
│   │   │   └── [...slug].astro
│   │   ├── 404.astro
│   │   ├── privacy.astro
│   │   └── terms.astro
│   ├── styles/             # Global CSS
│   ├── utils/              # Utility scripts and helpers
│   ├── consts.ts          # Site constants and configuration
│   └── content.config.ts  # Content collection schema definitions
├── public/
│   ├── fonts/             # Web fonts
│   └── media/             # Static assets served as-is
├── dev/
│   ├── design.json        # Complete design system documentation
│   └── continuity.md      # Development change log
├── astro.config.mjs       # Astro configuration
├── wrangler.jsonc         # Cloudflare Pages configuration
├── tsconfig.json          # TypeScript configuration
├── tailwind.config.js     # Tailwind CSS configuration
└── package.json           # Dependencies and scripts
```

## Architecture Overview

### Content-Driven Design

This site uses Astro's content collections for managing structured content:

- **Collections** defined in `src/content.config.ts` with TypeScript schema validation
- **Markdown & MDX** for rich, maintainable content
- **Type-safe** frontmatter with automatic validation

### Homepage Sections

The homepage is composed of modular Astro components that pull from MDX content:

1. **Hero** (`Hero.astro`) - Main banner with call-to-action
2. **Service List** (`ServiceList.astro`) - Primary services overview
3. **Service Areas** (`ServiceArea.astro`) - Geographic coverage
4. **Why Us** (`WhyUs.astro`) - Value proposition
5. **Expertise Mosaic** (`ExpertiseMosaic.astro`) - Visual showcase of work

### Blog System

- **Blog Index** (`src/pages/blog/index.astro`):
  - Fetches all posts with `getCollection('blog')`
  - Sorts by publication date (newest first)
  - Supports featured post highlighting
  - Implements category/tag filtering

- **Individual Posts** (`src/pages/blog/[...slug].astro`):
  - Automatic routing from MDX filenames
  - Previous/next post navigation
  - Related posts (same category/tags, max 3)
  - Reading time calculation (200 wpm)
  - Table of contents generation

### Routing

- **Static routes** in `src/pages/` → URLs
- **Blog routes** generated dynamically from `src/content/blog/`
- **Layouts** wrap pages with common structure
- **404 page** at `src/pages/404.astro`

## Design System

### Brand Colors

```css
--color-forest: #3A4D39    /* Primary brand color */
--color-sage: #739072      /* Secondary accent */
--color-cream: #ECE3CE     /* Background/neutrals */
```

### Typography

- **Headings**: Playfair Display (serif)
  - Bold, elegant, premium feel
  - Used for hero titles and section headings

- **Body**: Plus Jakarta Sans (sans-serif)
  - Modern, legible, friendly
  - Used for copy, navigation, UI

### Design Tokens

Complete design system reference available in `dev/design.json`:
- Color palette
- Typography scales
- Spacing system
- Component patterns
- Interactive states

## Image Handling

### Processed Images (`src/assets/`)

Images placed here are automatically optimized by Astro:

```astro
// Use relative paths
import heroImage from '../../assets/hero.jpg'
<img src={heroImage} alt="Hero image" />
```

Benefits:
- Automatic AVIF conversion
- Responsive image generation
- Optimization at build time

### Static Media (`public/media/`)

For videos, large files, or assets not needing optimization:

```astro
<!-- Use absolute paths -->
<video src="/media/video.mp4" />
```

## Content Management

### Creating Blog Posts

1. Create new file in `src/content/blog/` with `.mdx` extension
2. Include frontmatter with metadata:

```yaml
---
title: 'Painting Tips for Colorado Homes'
description: 'Expert advice for high-altitude painting projects'
pubDate: 'Jan 2 2026'
heroImage: '../../assets/blog-image.avif'
featured: false
category: 'Tips & Guides'
tags: ['painting', 'colorado', 'diy']
---

Your content here...
```

3. Post automatically appears on blog index sorted by date

### Editing Homepage Sections

Edit corresponding MDX files in `src/content/sections/`:
- `hero.mdx` - Hero banner content
- Experience section
- Skills section
- Featured project showcase

Changes are immediately reflected on homepage.

## Utility Scripts

### Image Optimization

Convert images to AVIF format for better performance:

```bash
# Convert all images
pnpm convert:avif:all

# Convert only JPEGs
pnpm convert:avif:jpeg

# Convert only PNGs
pnpm convert:avif:png
```

Utility: `src/utils/convert-to-avif.js`

### AI-Powered Commits

Generate commit messages using AI:

```bash
pnpm commit
```

Requires OpenRouter API key in `src/utils/.env`

### Cloudflare Type Generation

Generate TypeScript types for Cloudflare Workers:

```bash
pnpm cf-typegen
```

## Deployment Guide

### Prerequisites

- Cloudflare Pages project configured
- `wrangler.json` with proper configuration

### Automatic Deployment

The site is configured to deploy to Cloudflare Pages:

1. **Build**: Astro generates static HTML/CSS/JS in `./dist/`
2. **Deploy**: Cloudflare Pages serves the built site globally
3. **Edge Runtime**: Optional server-side functions via Cloudflare Workers

### Manual Deployment

```bash
# Build production bundle
pnpm build

# Preview locally before deploying
pnpm preview

# Deploy to Cloudflare Pages
pnpm deploy
```

### Environment Configuration

Set up environment variables in Cloudflare Pages:

```bash
PUBLIC_SITE_URL=https://summitpaintingcolorado.com
PUBLIC_SITE_NAME=Summit Painting & Handyman
```

### Cloudflare Configuration

Key settings in `wrangler.jsonc`:

```jsonc
{
  "name": "summit-painting-and-handyman-services",
  "compatibility_date": "2025-12-05",
  "env": {
    "production": {
      "name": "summit-painting-production"
    }
  }
}
```

## Development Workflow

### Making Changes

1. Create a feature branch: `git checkout -b feature/your-feature`
2. Make changes to content or components
3. Test locally: `pnpm dev`
4. Commit changes with: `pnpm commit` (or standard `git commit`)
5. Push to repository
6. Automatic deployment to Cloudflare Pages on merge to `main`

### Documenting Changes

Update `dev/continuity.md` when making significant changes:

- **What changed** - File modifications and new features
- **Why** - Reasoning behind decisions
- **Next steps** - Follow-up tasks or known limitations

### Testing Before Deploy

```bash
# Build and test
pnpm build
pnpm preview

# Check for TypeScript errors
# Linting/formatting (if configured)
```

## Configuration Files

### `src/consts.ts`
Site-wide constants and configuration values

### `astro.config.mjs`
Astro framework configuration:
- Site URL
- Integrations (React, MDX, Sitemap, RSS)
- Image optimization settings
- Output format and routing

### `wrangler.jsonc`
Cloudflare Pages deployment configuration:
- Project name
- Compatibility date
- Node.js API compatibility

### `dev/design.json`
Complete design system documentation for reference

### `CLAUDE.md`
Development guidance and architecture patterns for Claude AI assistant

## Performance Optimization

- **Static HTML** - Pre-rendered at build time
- **AVIF Images** - Modern format with ~25% smaller file sizes
- **Cloudflare CDN** - Global edge caching
- **No JavaScript** - Default rendering (React only for interactive sections)
- **Sitemap & RSS** - Automatic SEO feeds

## Support & Maintenance

- **Documentation**: See `CLAUDE.md` for development patterns
- **Design Reference**: Check `dev/design.json` for brand guidelines
- **Change Log**: Review `dev/continuity.md` for recent updates
- **Issues**: Address bugs and improvements through Git

## License

MIT

---

**Last Updated**: January 2, 2026