Add first cut at a CLAUDE.md file

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.