Skip to content
Ark

Context & domain language

The shared vocabulary of the Ark monorepo. Keep terms here precise and stable — code, docs, ADRs, and commit scopes should all use these words the same way. This is a living seed; deepen it as decisions land.

The repo

Section titled “The repo”
  • Ark — the 7hoenix monorepo (GitHub 7hoenix/ark, private, jj-colocated). Houses the apps, the shared packages they converge on, the release tooling, and this docsite.
  • Golden path — jg’s patterns, treated as the reference architecture the other apps converge toward. “On the golden path” = adopting the shared packages and conventions.
  • Convergence order (apps adopting shared packages): jg → trained → planter.
  • Move-in order (source landing in the repo): jg → mjolnir → trained → planter. Distinct from convergence — mjolnir moves in second but isn’t on the convergence track.

Apps

Section titled “Apps”
  • jg — spaced-repetition system (Entries, Firings, Interactions, Rotation, Reclassification). The golden-path reference; first app stood up end-to-end.
  • trained — chess training (Chess/ + Coach/ + Train/, Stockfish on lambda, scenario pipeline, iOS).
  • planter — roguelike for learning programming (parked until convergence Phase 6).
  • mjolnir — agent/workspace tooling; moves in second as apps/mjolnir, a golden-path consumer (its mj-app frontend rides the shared packages; engine crates are app-local).

Shared packages (end state)

Section titled “Shared packages (end state)”

app-core (Elm: Effect/Command/Reply dispatch, ports, routing, auth state machine) · ui (Elm: elm-book design system + Ui.Tokens + Tailwind v4 @theme) · tauri-core (Rust: crates/{api,core}, generate_elm codegen, build.rs iOS/env) · worker (TS: Cloudflare Worker — Apple OAuth, HS256 JWT, R2 event store) · chess-core (Elm/Rust: chess domain, sourced from trained).

Release & versioning vocabulary

Section titled “Release & versioning vocabulary”

Two separate tools, separate concerns (both support DRY_RUN=1):

  • scripts/release.sh — DEPLOYS. Targets: jg-ios, jg-api. Always promotes main@origin. Creates deploy-trigger tags server-side.
  • scripts/version.sh — repo-level VERSIONING via Knope across every package in knope.toml. Bumps, commits (jj-aware), and tags <pkg>/v<semver>.

Two tag schemes (both server-side via gh):

  • Deploy-trigger tags — jg-testflight-<N> (N = CFBundleVersion), jg-api-<sha>. Fire the prefix-guarded GitHub workflows.

  • Version markers — <pkg>/v<semver> (e.g. jg/v0.1.0). Knope baselines. Inert to the deploy workflows’ tag guards.

  • Knope — the versioning engine; knope.toml is the package registry. [packages.jg] has scopes = ["jg"].

  • Scope convention — app/library commits are package-scoped (feat(jg):, feat(ui):) and feed that package’s changelog + version. Repo-infra commits use non-package scopes (feat(ci):, chore(repo):, chore(release):, docs(...):) — excluded from every changelog and cannot bump any version.

Build / CI

Section titled “Build / CI”
  • moon — task runner + affected-graph + cache. moon ci runs CI-enabled tasks for the projects a change touches. Invoked as mise exec -- moon ….
  • bun — JS workspace backend (apps/*, packages/*); one bun install at the root.
  • runInCI: false — task opt-out (currently gen, rust, test-e2e: need cargo or a running dev-web harness, deferred until tauri-core).
  • mise — pins the toolchain (mise.toml): node, bun, rust, jj, moon.

Process

Section titled “Process”
  • RFC — proposal reviewed before building significant work. Lives in docs/rfcs/.
  • ADR — record of a decision already made (the “why”). Lives in docs/adr/.
  • Docsite — Astro Starlight site (apps/docs/) that renders everything in docs/, per-app docs, and per-package CHANGELOG.mds. Deployed to Cloudflare Pages (ark-docs.pages.dev) on merge to main, behind a Zero-Trust Access gate (email ends with @7hoenix.com). Setup + runbook: docs/reference/docsite-deploy.md.