diachron/CLAUDE.md

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.