Development: Structure

• LICENSE and README.md are self-explanatory.

• .envrc tells direnv where executables and tools are so that their directories may be added to the shell path.

• .gitignore specifies files and build artifacts not managed by git.

• GitLab CI/CD executes the .gitlab-ci.yml file when commits are pushed to the GitLab project repository.

• .justfile defines commands for just ↗︎. This is the most important file as it defines the top-level commands used in typical development tasks such as:

  • % just dev (or % just without any arguments) sets up the development environment and starts processes listed in the .procfile which incrementally rebuild parts of the Securepub site whenever a source file is changed.

  • % just build sets up the development environment, builds the local and local-s origin directories and adds them to the sp.zip file.

  • % just clean removes all build directories and artifacts.

  • % just veryclean does the work of % just clean and also removes all downloaded packages, node module directories, elm stuff directories and python virtual environments used during development.

• .procfile is a Procfile ↗︎ with processes Overmind ↗︎ runs during incremental development as described above.

• local.sh serves the local and local-s directories. It is also bundled in the sp.zip file built by % just build.

The article Introducing Overmind and Hivemind ↗︎ has a good introduction to how they work.

These files deal with things related to the overall project and third-party code.

work
│
├── .sync.py                    ⎞ files for python synchronizer
├── pylintrc                    ⎠  and code generator
│
├── pnpm-workspace.yaml         pnpm workspace
│
├── package.json                ⎞ patch files for npm modules
├── patches                     ⎠
│
├── vendor-j2e                  ⎞ vendored json-to-elm and
└── vendor-jsp                  ⎠  javascript-playgrounds

• .sync.py (and its pylintrc) provide the synchronization and code generation system which copies files from subdirectories of src/ to subdirectories of work/.

• pnpm-workspace.yaml lists all the workspace packages managed by pnpm ↗︎.

• package.json and the files in the patches directory apply minor changes to npm modules so that they work properly with Securepub.

• work/vendor-j2e holds a stripped-down version of json-to-elm ↗︎ by Alex Korban used to generate Elm flags decoders for Securepub. The .sync.py process runs this utility.

• work/vendor-jsp holds a stripped-down version of javascript-playgrounds ↗︎ by Devin Abbot sans embellishments (phone frames, python, typescript, etc) used to configure and interpret content bundle settings in the 21.bundle section of Securepub.

These files combine and compile the Elm modules into the _v1.2401_elm.js file with the Javascript code needed to render all the Elm views.

work
│
└── elm                         where elm code is compiled
    │
    ├── elm.ts                  ⎞ ts interface for Elm type
    ├── index.ts                ⎠
    │
    ├── package.json            how pnpm runs elm
    ├── elm.json                elm dependencies
    │
    ├── _elm.sh                 ⎞ script to post-process the
    ├── _elm.awk                ⎠ Javascript generated by Elm
    │
    └── src
        └── ...                 elm sources are copied here

• elm.ts and index.ts provide the Typescript interface specifying the Elm port send and subscribe functions.

• package.json identifies the Elm dependency and specifies the scripts run by pnpm.

• elm.json identifies the Elm modules Securepub uses.

• _elm.awk is called by _elm.sh to create a short bit of code to render a list of Dom nodes passed to Elm instead of just a single node. The code is patched into the generated Javascript with ex.

• _elm.sh has the logic to run elm-live or elm make and depending on context and adjust the output Javascript with _elm.awk so that the resulting Elm code will render views into multiple dom elements from a single model. The final _v1.2401_elm.js it generates is written to the Zola static directory.

• work/elm/src contains the files copied and generated by the _sync.py synchronization script which serve as input to elm-live and elm make.

These files combine and compile the Typescript modules into the _v1.2401_main.js and _v1.2401_uw.js files which allow Elm to interoperate with Userbase.

work
│
├── ts-configs                  shared typescript configuration
│   └── ...
│
├── auth                        ⎞
├── db                          ⎥ pnpm workspace packages
├── dbitems                     ⎥ for typescript modules.
├── dbmods                      ⎥
├── dbsources                   ⎥ each of these has
├── dbviews                     ⎥ package.json and tsconfig.json
├── entries                     ⎥
├── msg                         ⎥
├── progress                    ⎥
├── rcache                      ⎥
├── settings                    ⎥
├── share                       ⎥
├── types                       ⎥
├── util                        ⎠
│
├── uw                          userbase web worker module
└── main                        Securepub main module

shared ts-configs

• work/ts-configs/ contains a collection of Typescript configuration files organized by the corresponding section of the tsconfig ↗︎ documentation. The various tsconfig.json in each Securepub module extend these files, occasionally overriding compilerOptions for their situation.

internal modules

Each of the following Typescript modules is copied by .sync.py from src/ according to the specified directive.

main builds _v1.2401_main.js

uw builds _v1.2401_uw.js

work
│
├── sw-s                        secure origin service worker module
└── review-s                    secure origin review module

These modules are copied by .sync.py from src/ according to the specified directive.

work
│
└── zola                        where zola is run
    │
    ├── package.json            ⎞ how pnpm runs zola
    ├── _zola.sh                ⎠
    │
    ├── prettierrc.json         ⎞ prettier config to validate
    ├── .prettierignore         ⎠ generated html files
    │
    ├── translations.toml       ⎞ zola translations and configs
    ├── conf                    ⎥ combined into config.toml
    │   └── ...                 ⎠
    │
    ├── content                 ⎞
    │   ├── _index.md           ⎥ zola content files
    │   ├── _index.sp.md        ⎥
    │   └── _v1.2401_           ⎥
    │       └── ...             ⎠
    │
    ├── static                  ⎞ zola static assets
    │   └── _v1.2401_           ⎥  .js output files
    │       └── ...             ⎠
    │
    └── templates               ⎞ zola templates and shortcodes
        └── shortcodes          ⎠  used by markdown content

• package.json specifies the prettier dependency and specifies the scripts run by pnpm.

• _zola.sh generates Zola's config.toml by merging a specified conf/ file and translations.toml and then launches zola build, prettier and/or zola serve as appropriate.

• prettierrc.json and .prettierignore tell prettier what configuration it should use and what files to ignore for Securepub.

• translations.toml contain the Zola translations used for the Securepub menu.

• the work/zola/conf directory holds different base Zola configurations for each build environment.

• the work/zola/content directory contains the files copied and generated from src/which build the final site.

• the work/zola/static directory contains static assets and the final generated Javascript files from Typescript and Elm.

The Securepub pages section and the the Zola Overview ↗︎ provide more details.

work
│
└── zola-s
    │
    ├── package.json            ⎞
    ├── _zola-s.sh              ⎥ zola configuration for
    ├── prettierrc.json         ⎥  secure origin site
    ├── conf                    ⎥
    ├── content                 ⎥
    ├── static                  ⎥
    └── templates               ⎥
        └── shortcodes          ⎠

The contents are much the same as described for the work/zola directory.
The scripts and config files differ in predictable ways.