Michael Wolf
eb12471941
Platform detection now happens in framework/platform, sourced by both sync.sh and the node shim. Uses shasum on macOS, sha256sum on Linux. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
123 lines
3.1 KiB
Markdown
123 lines
3.1 KiB
Markdown
# 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 express && ../cmd pnpm biome check --write .
|
|
```
|
|
|
|
**Build Go master process:**
|
|
```bash
|
|
cd master && go build
|
|
```
|
|
|
|
### Operational
|
|
|
|
(to be written)
|
|
|
|
## Architecture
|
|
|
|
### Components
|
|
|
|
- **express/** - 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)
|
|
|
|
### Express 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.
|