# 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.