Schematra Starter Kit

A starter kit for building web applications in CHICKEN Scheme using the Schematra web framework. Comes with an ORM (RQLite-backed), session management, OAuth, background job processing, HTMX integration, and production deployment infrastructure out of the box.

What's Included

• Schematra web framework with routing, middleware, and session support
• Chiccup templating (hiccup-style HTML in Scheme) with Tailwind CSS and HTMX
• ORM with auto-generated CRUD operations backed by RQLite
• OAuth authentication (Google, extensible to other providers)
• Background worker with Redis-based job scheduling and Fibonacci retry backoff
• AWS SDK — SES (email), SSM (parameter store), S3 (object storage), STS
• Production deployment — Terraform configs for Linode + Cloudflare DNS + Caddy reverse proxy

Development Environment

The entire dev loop — compiler, dependencies, database, Redis — runs inside Docker. You edit source files on your host with whatever editor you prefer; everything else happens in containers.

Why Docker-only:

• Zero local setup — no need to install CHICKEN Scheme, egg dependencies, or kdp-build on your machine. The dev image has everything.
• Reproducible — every developer gets the exact same toolchain, no "works on my machine" issues.
• Isolated infrastructure — RQLite and Redis run inside the compose network with no ports exposed to the host. Multiple Schematra projects can run simultaneously without port conflicts (use APP_PORT to pick different host ports).
• Same base as production — the dev image is the same Dockerfile stage that production builds extend, so you're always building against the real thing.

Want to run outside Docker? The Dockerfile is the canonical reference for setting up CHICKEN, kdp-build, and all dependencies. Follow the base stage step by step to replicate the environment on your host.

Getting Started

With Claude Code (recommended)

If you have Claude Code installed, run this one-liner to download the skill and create a new project:

claude --allowedTools 'Bash(curl *)' 'Bash(git *)' 'Bash(mkdir *)' 'Write' \
  -p 'use curl to download the skill definition from https://forgejo.rolando.cl/cpm/schematra-starter-kit/raw/branch/main/.claude/skills/schematra-app/SKILL.md and run /schematra-app <my-project>'

This fetches the /schematra-app skill, clones the starter kit, and initializes a fresh git repo. Then follow the instructions to continue setup in the new project directory with /schematra-app continue, which walks you through installing dependencies, configuring services, and running the app.

Once your project is set up, use /schematra-deploy to configure production infrastructure.

Manual Setup

All development happens inside Docker — no local CHICKEN install needed.

# Clone and initialize
git clone https://forgejo.rolando.cl/cpm/schematra-starter-kit my-project
cd my-project
rm -rf .git && git init && git add -A && git commit -m "Initial commit"

# Create a .env file
cat > .env <<EOF
APP_URL=http://localhost:8080
EOF

# Build the dev image (installs CHICKEN, kdp-build, and all dependencies)
docker compose build dev

# Start dev container with RQLite and Redis
docker compose run --rm --service-ports dev

Inside the container:

kdp-build -j $(nproc)    # build modules
csi                       # start REPL

Inside the REPL:

,l app.scm

Visit http://localhost:8080 to confirm the app is running.

Development Workflow

After making changes, rebuild and reload:

kdp-build -j $(nproc)   # in a separate terminal/container

,l app.scm        ;; in the running REPL

To use a different host port (e.g. for multiple projects):

APP_PORT=9090 docker compose run --rm --service-ports dev

Project Structure

app.scm                 # Web application entry point
d-worker.scm            # Background worker entry point
d-scheduler.scm         # Redis-based job scheduler
routes.scm              # Main routes
*.routes.scm            # Feature-specific routes
*.views.scm             # View modules (Chiccup components)
models.scm              # Model definitions (auto-runs migrations)
migrations.scm          # Database schema migrations
dotenv.scm              # Environment variable loader
utils.scm               # Shared utilities
aws.scm                 # AWS SDK (SES, SSM, S3, STS)
assets/                 # Static assets (served at /assets)
ops/                    # Terraform deployment configs
build.lsp               # kdp-build spec (web)
build.worker.lsp        # kdp-build spec (worker)
CLAUDE.md               # Full API reference and coding patterns
ORM.md                  # ORM documentation

Documentation

• CLAUDE.md — Complete API reference: routing, request handling, responses, views, middleware, sessions, authentication, coding patterns
• ORM.md — Database model definitions, migrations, and query API
• DSCHEDULER.md — Background job scheduler documentation

Prerequisites

• Docker (everything runs inside Docker — no local CHICKEN install needed)