You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Engineering documentation portal and browser-based utilities for mechanical design, fabrication, QA workflows, and CAD automation. All tools run client-side in Chromium with WebGL 2 and WebAssembly.
# Install dependencies
npm install
# Start development server
npm start
# Build for production
npm run build
# Serve production build locally
npm run serve
UI strings live in src/i18n/locales/*.ts (6 locales: en, ru, ua, de,
es, et). Rule: never hardcode user-facing strings in components — add a
key to all six dictionaries and render it with t('section.key') from
useI18n().
How completeness is enforced
en.ts exports the TranslationDict type, and every other locale is declared
against it (export const de: TranslationDict = {...}). A key missing from any
locale is therefore a type error: npm run typecheck fails locally, and CI
(.github/workflows/ci.yml) runs the same check on every PR and push to
main, so an incomplete translation cannot be merged.
Adding or changing a string
Add the key and English text to src/i18n/locales/en.ts — this updates
TranslationDict, and typecheck now lists every locale still missing it.
Add the translated value to the same path in ru.ts, ua.ts, de.ts,
es.ts, and et.ts.
Render it with t('section.key'); placeholders use {name} syntax and are
passed as the second argument: t('utility.unlockCopy', {name: title}).
Run npm run typecheck before pushing.
Docusaurus-native surfaces
The navbar, footer, docs sidebar, and other theme-owned UI are translated via
JSON in i18n/<locale>/**.json instead (regenerate stubs with
npm run write-translations). Markdown/MDX content (docs, blog) is localized
by mirroring files under i18n/<locale>/docusaurus-plugin-content-*/.
Build and republish the Heat Input Master artifact
npm run sync:webstep-viewer
Sync WebSTEP viewer embed
npm run sync:whisper-transcriber
Build and republish the Whisper Transcriber artifact
Deployment
The site is deployed on Vercel: every push to main triggers a production deployment, and pull requests get preview deployments. CI (.github/workflows/ci.yml) runs typecheck, lint and a full build on every PR.
Manual Deployment
# Build production bundle
npm run build
# Deploy build/ directory to your hosting platform
Create a feature branch: git checkout -b feature/my-feature
Commit changes: git commit -m 'Add my feature'
Push to branch: git push origin feature/my-feature
Open a Pull Request
Adding a New Utility
Before the steps below, decide where the code should live — a standalone
micro-app, an in-repo React component, or (never for new tools) a legacy HTML
page. dev-plans/utility-development-workflow.md
explains the three shapes, when each applies, and why scratch copies of shipped
tools must be deleted rather than kept.
For what a utility must satisfy before it ships — engine tests, published
validation cases, manual checklists for DXF/STEP/PDF handling, and platform
expectations — see the
Testing and QA strategy
(source).
Add utility metadata to src/data/utilities.ts
Add the slug and shell config to src/data/utilityShellPages.tsx
Create page route in src/pages/utilities/
Add documentation in docs/utilities/ plus the five i18n/<locale>/…/utilities/ mirrors, and list it in sidebars.ts and utilities/overview.mdx
Add the catalog name/description to all six src/i18n/locales/*.ts dictionaries
Place standalone build assets in static/utility-apps/<slug>/ if needed
Embedded apps built in their own repository
Utilities too heavy to live in the Docusaurus bundle are built elsewhere and
published here as static artifacts. The Whisper Transcriber is the reference
implementation of that pipeline:
Merging application code to main in
YurMil/ws-speech-text builds the
bundle, tests and audits it, and attaches a checksummed archive to a GitHub
release. (Documentation-only merges there do not release.)
That workflow sends a whisper-transcriber-releaserepository_dispatch here
(secret SITE_DISPATCH_TOKEN, set in the source repository).
.github/workflows/sync-whisper-transcriber.yml downloads the archive,
refuses it unless the SHA-256 matches, republishes
static/utility-apps/whisper-transcriber/ via
scripts/sync-whisper-transcriber.mjs, runs typecheck/lint/build, and opens
a pull request on the rolling chore/whisper-transcriber-sync branch —
updated in place, so successive releases never queue up as separate pull
requests.
Nothing is deployed without review, and this repository never builds the app or
downloads model weights. The same script publishes from a local checkout during
development (npm run sync:whisper-transcriber).
Repository setting this depends on:Settings → Actions → General → Workflow
permissions must have "Allow GitHub Actions to create and approve pull
requests" enabled, or the sync publishes the branch and then cannot open the
request for it. Optionally add a SYNC_PR_TOKEN secret holding a PAT that can
open pull requests — requests opened by the default token do not trigger
on: pull_request workflows, so they arrive showing no checks even though the
sync job ran typecheck, lint and the full build before pushing.
Device capabilities
Device capabilities (camera, microphone) are delegated per utility through the
iframeAllow field of UtilityPageConfig, paired with a path-scoped
Permissions-Policy rule in vercel.json. Never widen the global policy: the
site default stays microphone=(), and only the routes of the utility that
needs a device relax it. See whisper-transcriber for the reference wiring.
License
This project is licensed under the MIT License - see LICENSE for details.
About
The idea is to create a knowledge base covering automation methods for mechanical engineers, electrical engineers, technologists, and others who work with various CAD systems or simply face routine engineering tasks.
