SideDoc

Appearance

ADR 0001: One monorepo for the code, a separate repository for the schemas ​

  • Status: accepted
  • Date: 2026-10-19
  • Evidence: commits 2186bb6 (start monorepo), ca9208a and b51ab3f (backend and frontend added with git subtree, history kept), 4d401ea (schemas from SIDEDOC_SCHEMAS_DIR), ede9831 (npm workspaces root)

Context ​

Until October 2026 SideDoc lived in three repositories next to each other: sidedoc-backend, sidedoc-frontend and the schemas. The frontend depended on the backend as file:../sidedoc-backend, so CI had to clone the backend as a sibling, build it with tsup and then install the frontend (see the legacy app/sidedoc-frontend/.gitlab-ci.yml). A change that touched both packages needed two merge requests that had to land together. The build scripts assumed a sibling ../Schemas folder, which broke on case-sensitive file systems.

The schemas have a different life cycle. They are generated from a Google Sheet by Python scripts, are versioned and published per datamodel version, and are also consumed outside the editor (DCAT-AP alignment, SHACL validation, documentation).

Decision ​

  • Merge backend and frontend into one repository (gitlab.com/sidedoc/sidedoc) with npm workspaces and one lockfile: app/sidedoc-backend, app/sidedoc-frontend and later docs. Both were imported with git subtree so their history is kept.
  • Keep the schemas in their own repository (gitlab.com/sidedoc/schemas).
  • Build scripts and tests that need schema files read them from SIDEDOC_SCHEMAS_DIR, with a schemas/ folder in the repository root as fallback, and stop with a clear message when neither exists.
  • Files the app needs at run time are committed as copies: public/schemas/, public/vocab*/, the vocabulary index and the DCAT mapping copies in the backend.

Consequences ​

  • Backend and frontend changes go in one merge request. Root scripts (build, typecheck, test) cover both.
  • The container image and a plain frontend build do not need a schemas checkout, because the copies are committed.
  • Developers need two clones and SIDEDOC_SCHEMAS_DIR to rebuild the backend or run the DCAT tests.
  • Committed copies can drift from the schemas repository. Regenerating them is an explicit chore: commit.
  • The old per-package CI file no longer runs; the monorepo needs its own pipeline.