Sunday, 12 July 2026

Roject — Session Summary

Full project directory restructure — source/, build/app/, build/data/, source/pages/ with a copy-pages build step.

What we built

Directory restructure

The project root was reorganised into two top-level directories that cleanly separate source from build artefacts and runtime data:

  • source/ — all TypeScript source (components, editor, server, rojos, locales, library-ts submodule) plus locale data and HTML pages
  • build/app/ — compiled frontend output (was public/)
  • build/data/db/ — JSON user/project data (was data/)
  • build/data/storage/ — project files, sessions, layouts (was storage/)

The git submodule (library-ts) was moved with git mv so .gitmodules stayed in sync automatically. The entire build/ tree is gitignored; source/ is fully tracked.

source/ build/app/ build/data/ git mv

source/pages/ + copy-pages build step

HTML pages (editor.html, dashboard.html, etc.) moved from build/app/ into source/pages/ so they are tracked in git as source files. A new scripts/copy-pages.js (plain Node.js, no extra dependencies) copies them to build/app/ as the second step of npm run build: 

tsc --build tsconfig.client.json && node scripts/copy-pages.js
source/pages/ scripts/copy-pages.js npm run build

Key Decisions

Two locale directories: source/locales/ vs source/locale-data/

src/locales/ (TypeScript locale management code) moved to source/locales/. The root locales/ (raw locale data files — en/) moved to source/locale-data/. Merging them into one directory would have mixed TypeScript source with data files; keeping them separate makes each directory's purpose unambiguous.

build/ fully gitignored, source/pages/ tracked

The old setup had public/ gitignored with a !public/*.html exception that never actually tracked the files. The new setup is cleaner: all hand-written HTML pages live in source/pages/ (tracked), build/ is entirely ignored, and the copy step bridges the two at build time.

Plain Node.js copy script, no npm dependency

scripts/copy-pages.js uses only fs and path from the Node.js standard library. Adding a package like copyfiles or cpx for a four-line operation would be unnecessary complexity.

Structural Changes

src/ → source/ (git mv, including library-ts submodule)
server/ → source/server/ (git mv)
locales/ → source/locale-data/ (git mv)
public/ → build/app/ (filesystem move, gitignored)
data/ → build/data/db/ (filesystem move, gitignored)
storage/ → build/data/storage/ (filesystem move, gitignored)
source/pages/ — new: hand-written HTML pages (tracked)
scripts/copy-pages.js — new: copies pages to build/app/ on build
tsconfig.client.json — rootDir, outDir, include, exclude, references updated
tsconfig.json — include updated
tsconfig.ts-node.json — include updated
source/library-ts/browser/tsconfig.roject.json — outDir updated
package.json — main and build script updated
.gitignore — replaced data/, storage/, public/ with build/
source/server/ — all __dirname paths and library-ts imports updated