CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SkyShot is a screenshot-as-a-service microservice built with Skykit. It captures full-page screenshots of websites using headless Chrome and serves them via REST API.

Development Commands

# Run with Docker (recommended)
docker build -t skyshot .
docker run -p 5000:5000 skyshot

# Run locally (requires Chromium)
go run .

# Build
go build -o skyshot .

# Test screenshot
curl http://localhost:5000/myapp -o test.png

Architecture

Project Structure

skyshot/
├── main.go                 # Entry point with embedded default image
├── controllers/
│   └── screenshots.go      # Screenshot capture and serving
├── models/
│   ├── database.go         # Database connection
│   └── screenshot.go       # Screenshot model and chromedp logic
├── views/
│   └── home.html           # Homepage
└── resources/
    └── default.png         # Embedded fallback image

Route Handlers

Screenshot Model

type Screenshot struct {
    skykit.Model
    ImageData []byte  // PNG bytes stored in database
}

ID is the app name (not auto-generated UUID).

Capture Flow

1. Request comes in for /{app}
2. Check database for cached screenshot
3. If found, serve with 24-hour cache header
4. If not found, serve default image and trigger background capture
5. Background capture uses chromedp with configurable timeout
6. Screenshot stored in database for future requests

Concurrency Control

type ScreenshotsController struct {
    skykit.Controller
    defaultImg []byte           // Embedded fallback
    mutex      *sync.Mutex      // Protects capturing map
    capturing  map[string]bool  // Prevents duplicate captures
}

chromedp Integration

Located in models/screenshot.go. Uses:

• chromedp.Navigate(url) - Load the page
• chromedp.WaitReady("body") - Wait for DOM
• chromedp.FullScreenshot(&buf, quality) - Capture PNG

Environment Variables

Docker Requirements

The Dockerfile installs Chromium:

RUN apt-get update && apt-get install -y chromium chromium-sandbox
ENV CHROME_BIN=/usr/bin/chromium

Dependencies

• theskyscape.com/repo/skykit - Web framework (local via replace)
• github.com/chromedp/chromedp - Headless Chrome automation