# 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:**
```bash
./sync.sh
```

**Run an app:**
```bash
./master
```



### Development

**Check shell scripts (shellcheck + shfmt) (eventually go fmt and biome or similar):**
```bash
./check.sh
```

**Format TypeScript code:**
```bash
cd backend && ../cmd pnpm biome check --write .
```

**Build Go master process:**
```bash
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
- **framework/** - 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` → `framework/cmd.d/*` → `framework/shims/*` → managed binaries in `framework/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.