diachron/CLAUDE.md

CLAUDE.md

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

Project Overview

Diachron is an opinionated TypeScript/Node.js web framework with a Go-based master process. Key design principles:

• No development/production distinction - single mode of operation everywhere
• Everything loggable and inspectable for debuggability
• Minimal magic, explicit behavior
• PostgreSQL-only (no database abstraction)
• Inspired by "Taking PHP Seriously" essay

Commands

General

Install dependencies:

./sync.sh

Run an app:

./master

Development

Check shell scripts (shellcheck + shfmt) (eventually go fmt and biome or similar):

./check.sh

Format TypeScript code:

cd backend && ../cmd pnpm biome check --write .

Build Go master process:

cd master && go build

Operational

(to be written)

Architecture

Components

• backend/ - TypeScript/Express.js backend application
• master/ - Go-based master process for file watching and process management
• diachron/ - Managed binaries (Node.js, pnpm), command wrappers, and framework-specific library code
• monitor/ - Go file watcher that triggers rebuilds (experimental)

Master Process (Go)

Responsibilities:

• Watch TypeScript source for changes and trigger rebuilds
• Manage worker processes
• Proxy web requests to backend workers
• Behaves identically in all environments (no dev/prod distinction)

Backend App Structure

• app.ts - Main Express application setup with route matching
• routes.ts - Route definitions
• handlers.ts - Route handlers
• services.ts - Service layer (database, logging, misc)
• types.ts - TypeScript type definitions (Route, Call, Handler, Result, Method)

Framework Command System

Commands flow through: ./cmd → diachron/cmd.d/* → diachron/shims/* → managed binaries in diachron/binaries/

This ensures consistent tooling versions across the team without system-wide installations.

Tech Stack

• TypeScript 5.9+ / Node.js 22.15
• Express.js 5.1
• Go 1.23.3+ (master process)
• pnpm 10.12.4 (package manager)
• Zod (runtime validation)
• Nunjucks (templating)
• @vercel/ncc (bundling)

Platform Requirements

Linux or macOS on x86_64. Requires:

• Modern libc for Go binaries (Linux)
• docker compose (for full stack)
• fd, shellcheck, shfmt (for development)

Current Status

Early stage - most implementations are stubs:

• Database service is placeholder
• Logging functions marked WRITEME
• No test framework configured yet

meta

formatting and sorting

• When a typescript file exports symbols, they should be listed in order

guidelines for this document

• Try to keep lines below 80 characters in length, especially prose. But if embedded code or literals are longer, that's fine.
• Use formatting such as bold or italics sparingly
• In general, we treat this document like source code insofar as it should be both human-readable and machine-readable
• Keep this meta section at the end of the file.