From 8e5b46d4267516d64e04cf3e02b7f0cf4398a1e1 Mon Sep 17 00:00:00 2001 From: Michael Wolf Date: Thu, 1 Jan 2026 12:31:35 -0600 Subject: [PATCH] Add first cut at a CLAUDE.md file --- CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b2d4407 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,69 @@ +# diachron overview for Claude + +## Overview + +diachron is an attempt at a web framework that attempts to solve various pain +points I've dealt with when using other frameworks. + +## Goals + +- Programs are increasingly complicated; therefore: + - We want to have everything loggable available for inspection + - At any given point in execution execution, we want to know "what the + framework thinks" + - Easy debuggability is very important +- We don't want extreme flexibility; for example, by design we only support + Postgres +- We don't aim to be fast (it's nice when we can get good performance, but it + should be sacrificed to other goals most of the time) +- Application Diachron code uses Typescript; however, it draws a lot of ideas + from the essay titled "Taking PHP Seriously" +- We want as little magic as possible +- When it comes to behavior or architecture, there must be no + development/production distinction. Just one mode of operation. + + +## architecture + +Note: for now, this document only describes the part of the framework that is +involved with processing requests and creating responses. + +### master process + +The master process is written in golang. It has the following +responsabilities: + +- Listen on one or more ports and proxy web requests to the correct backend + worker +- Watch the typescript source directory for changes; when it changes, attempt + to rebuild the typescript source + - Keep numerous copies of the transpiled system available + - If transpiliation fails, execution should not stop +- Keep track of child processes, ensuring that a sufficient number of them are + available at a given time. + +Note that the master process behaves exactly the same in production +environments as it does on a developer's desktop system. There is no +development/production distinction. + + + +## Project structure + +# meta + +## plans + +- This document includes many statements that should be taken as statements of + intent and not necessarily of current fact. In other words, when diachron + reaches a certain stage of maturity, the entire document should be true, but + initially it is not yet entirely true. + +## 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.