[OCaml] High Intensity Training Online
docs add a README for a human skimming the repository
The repository had no top-level entry point. Say what hito is and which doctrine it encodes, lay out the six libraries and the inward-only dependency rule, show how to build and run it with every environment variable, and name the three gates that define done.
README.md
@@ -0,0 +1,76 @@
1
Added:
# hito
2
Added:
3
Added:
A Heavy Duty training tracker. hito records workouts the way Mike Mentzer's
4
Added:
Heavy Duty prescribes them: one working set to failure per exercise, recovery
5
Added:
gating the next session, and progress measured as more reps or more load.
6
Added:
7
Added:
The domain refuses states the doctrine cannot read. A routine cannot exceed
8
Added:
three sets per muscle. A workout cannot begin before recovery without an
9
Added:
explicit, recorded override. A stall is corrected by resting more and doing
10
Added:
less, never by adding work.
11
Added:
12
Added:
## Layout
13
Added:
14
Added:
Six libraries, dependencies pointing inward only. The build graph enforces
15
Added:
the rule: a library cannot name what it does not link.
16
Added:
17
Added:
| Library | Role |
18
Added:
|--------------------|---------------------------------------------------------------|
19
Added:
| `hito.core` | Pure domain. No framework, database, or Lwt. |
20
Added:
| `hito.app` | Ports (`Repository`, `Password_hash`, `Importer`), `Service`. |
21
Added:
| `hito.import` | Adapters for third-party exports (`Hevy_csv`). |
22
Added:
| `hito.persistence` | SQLite adapter, bcrypt adapter, stored-record codecs. |
23
Added:
| `hito.presenter` | View models and pages. Depends on Dream only. |
24
Added:
| `hito.web` | Controllers. Maps entities to view models. |
25
Added:
26
Added:
`bin/` is the composition root: it alone names both an adapter and the port
27
Added:
it plugs into.
28
Added:
29
Added:
## Run
30
Added:
31
Added:
hito needs OCaml 5.1 or later and the pinned dependencies in `hito.opam`.
32
Added:
33
Added:
```sh
34
Added:
opam install . --deps-only --with-test
35
Added:
dune build
36
Added:
dune exec hito
37
Added:
```
38
Added:
39
Added:
Configuration comes from the environment. All variables have defaults.
40
Added:
41
Added:
| Variable | Purpose |
42
Added:
|----------------------|------------------------------------------------------------|
43
Added:
| `HITO_DB` | Caqti URI. Default `sqlite3:local_db/hito.sqlite`. |
44
Added:
| `HITO_SECRET` | Signs sessions and CSRF tokens. Set it in production. |
45
Added:
| `HITO_PORT` | TCP port. Default `8080`. The server binds loopback. |
46
Added:
| `HITO_VERSION` | Deployment identifier shown in the footer. |
47
Added:
| `HITO_SEED` | `1` seeds one account on startup. Default `0`. |
48
Added:
| `HITO_SEED_PASSWORD` | Required when `HITO_SEED=1`. |
49
Added:
| `HITO_SEED_CSV` | Hevy export imported for the seeded account. |
50
Added:
51
Added:
Sessions live in a signed cookie. The server sets a same-origin content
52
Added:
security policy and refuses framing. Put a TLS-terminating proxy in front of
53
Added:
it.
54
Added:
55
Added:
## Develop
56
Added:
57
Added:
Three gates define done, in this order. `scripts/ci.sh` runs all three and
58
Added:
exits non-zero on any failure.
59
Added:
60
Added:
```sh
61
Added:
dune build @check # type-check libraries and tests
62
Added:
dune runtest # every Alcotest suite
63
Added:
dune build @fmt # ocamlformat and dune formatting applied
64
Added:
```
65
Added:
66
Added:
Format with `ocamlformat --inplace` on the files you touched. Run
67
Added:
`scripts/install-hooks.sh` once per clone to run the gates before every push.
68
Added:
`scripts/coverage.sh` renders a coverage report when `bisect_ppx` is
69
Added:
installed.
70
Added:
71
Added:
## Doctrine
72
Added:
73
Added:
Design decisions answer to *Heavy Duty I*. The steering files under
74
Added:
`.kiro/steering/` state the principles the model encodes and the rules the
75
Added:
code follows. The book itself is copyrighted reference material and is not
76
Added:
part of the repository.