Workflow & Checks
Branching model
Section titled “Branching model”| Branch | Purpose |
|---|---|
main |
Released code (Stable updater channel). Updated only via release pull requests from dev. |
dev |
Integration branch (Nightly updater channel). All feature and fix PRs branch from and target dev. |
<area>/<topic> |
Feature or fix branches (for example networks/signal, ui/inbox, docs/starlight). |
- Never commit directly to
mainordev. - Stack dependent work on its prerequisite branch and target that branch until it merges.
- Every pull request requires passing checks and an independent review.
Working in git worktrees
Section titled “Working in git worktrees”Give each branch its own worktree under .worktrees/ (gitignored) so multiple branches can run simultaneously:
git fetch origingit worktree add -b networks/signal .worktrees/signal origin/devcd .worktrees/signalpnpm install && pnpm dev --setupRemove the worktree once its PR merges:
git worktree remove .worktrees/signalPre-PR checks
Section titled “Pre-PR checks”Run the full check suite from the repository root before opening a pull request:
pnpm checkpnpm check mirrors .github/workflows/checks.yml:
pnpm typecheckpnpm lint(oxlintwith type-aware checks, Convex plugin rules, and design system rules)pnpm test(Vitest across all TypeScript packages andconvex-test)pnpm test:scripts(Node test runner forscripts/)go vet ./...andgo test ./...insideapps/bridge-host
Design system lint rules
Section titled “Design system lint rules”pnpm lint enforces three custom rules (scripts/lint/design-system.mjs) in apps/desktop and packages/ui:
| Rule | Scope | Requirement |
|---|---|---|
trioditis/no-literal-colour |
apps/desktop, packages/ui |
No hex, rgb(), or hsl() literals—always use design tokens from packages/ui/src/styles/tokens.css |
trioditis/no-raw-control |
apps/desktop |
Use @trioditis/ui primitives instead of raw <button>, <input>, <select>, or <textarea> |
trioditis/ui-imports |
apps/desktop |
Import one component at a time (e.g. @trioditis/ui/button) |
Only disable a rule for a single line with an inline explanation:
// eslint-disable-next-line trioditis/no-raw-control -- reason
Keeping contracts in sync
Section titled “Keeping contracts in sync”- TypeScript ↔ Go: Any change to the Sealed Storage Spec or Bridge Protocol must update both TypeScript (
packages/crypto,packages/core,packages/backend,apps/gateway) and Go (apps/bridge-host) in the same pull request, including shared test vectors. - No plaintext leaks: Never write plaintext message bodies, chat names, or contact names to Convex, logs, or unencrypted disk.
- No auto-retry after ambiguity: Always surface the
unknowndelivery state rather than silently resending. - Release notes: User-visible changes add a short note under
release-notes/, which the server updater surfaces in Admin settings → Updates.
Desktop releases
Section titled “Desktop releases”A desktop release is tagged on a release merge commit on main (which matches what servers on the Stable update channel run):
git fetch origin && git tag v0.1.0 origin/maingit push origin v0.1.0Pushing a v<version> tag triggers .github/workflows/desktop-release.yml, building native installers on macOS (Apple Silicon and Intel, ad-hoc signed), Windows (x64), and Linux (AppImage and .deb) and publishing them with SHA-256 checksums to GitHub Releases. Pre-release tags (such as v0.2.0-beta.1) publish as GitHub prereleases without moving the releases/latest download links. Note that electron-builder.yml packages only the Electron shell and server picker—the web app comes directly from your Trioditis server.
Repository layout
Section titled “Repository layout”apps/ bridge-host/ Go: bridgev2 MatrixConnector, 12 connectors, sealing, journal, login-browser desktop/ Web & Electron desktop app (Vite + TanStack Router/Query) docs/ Astro Starlight documentation site (all project docs live in src/content/docs/) gateway/ Node: bridge host ↔ Convex pipeline & sign-in browser proxy site/ Project landing pageassets/ brand/ Generated brand SVGs, PNGs, favicon, and social cardpackages/ backend/ Convex schema, queries, mutations, Better Auth, MCP server brand/ Brand asset generator (pnpm --filter @trioditis/brand generate) config/ Shared TypeScript configuration core/ Shared domain types and bridge protocol wire types crypto/ Sealed storage, key wrapping, Argon2id password derivation ui/ Design tokens, Wordmark, and UI component primitivesdeploy/ compose/ Docker Compose bundle, Caddyfile, network overlays docker/ Pinned Dockerfiles (web, node, bridge-host, login-browser) install/ install.sh and proxmox.sh scripts/ Key generation, encrypted backups, admin CLI, migrations, updater agent test/ Automated deployment bundle test suiterelease-notes/ Per-change release notes shown by the updaterscripts/ Dev stack and CI check runner