70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# 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.
|