Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
85 lines (66 loc) · 4.46 KB

ARCHITECTURE.md

File metadata and controls

85 lines (66 loc) · 4.46 KB
Raw

Architecture

shared-libs/ groups shared Rust crates and TypeScript modules. Each sub-library has its own detailed ARCHITECTURE.md; this file only explains how the two pieces relate to the rest of the monorepo.

Place in the monorepo

shared-libs/ sits at the repo root and holds crates/ (the backend and supporting Rust crates) and ts-modules/ (shared TypeScript modules) — that the thin product crates and apps under projects/ consume. It builds nothing of its own. See the root ARCHITECTURE.md for the overall monorepo layout.

crates/start-core — Rust backend

The complete StartOS backend, published as Cargo package start-core with lib name start_core ([lib] name = "start_core"). It is part of the single root Cargo workspace and shares the one Cargo.lock.

The OS, CLI, registry, and tunnel binaries are thin wrappers that depend on this crate:

Binary Product crate Source
startbox / start-container start-os projects/start-os/src/bin/*.rs
start-cli start-cli projects/start-cli/src/main.rs
registrybox start-registry projects/start-registry/src/main.rs
tunnelbox start-tunnel projects/start-tunnel/src/main.rs

startwrt (projects/start-wrt/backend/ctrl/src/bin/startwrt.rs) also depends on start-core, aliased as startos, but owns its router backend rather than wrapping the shared entrypoints. Other shared crates include exver, imbl-value, jsonpath, patch-db, pi-beep, rpc-toolkit, and yasi.

Key module groups under crates/start-core/src/ include bins, service, s9pk, net, db, install, update, lxc, os_install, backup, sign, version, registry, and tunnel. It consumes the patch-db Rust core from the first-party shared-libs/crates/patch-db/ (patch-db = { path = "../patch-db/core" }). See crates/start-core/ARCHITECTURE.md for the internal design.

ts-modules — shared TypeScript modules (workspace rooted at repo root)

The single Angular workspace root for every front end is at the monorepo root: angular.json, package.json, and package-lock.json live at the repo root, and app projects define their UIs in their own web/ subdirectories (e.g. projects/start-os/web/, projects/start-tunnel/web/).

shared-libs/ts-modules/ holds shared TypeScript modules; two Angular source libraries and one non-Angular core lib:

  • shared-libs/ts-modules/shared/ → @start9labs/shared — API clients, shared components, i18n dictionaries, and global styles used by every UI.
  • shared-libs/ts-modules/marketplace/ → @start9labs/marketplace — service discovery / marketplace UI, shared between the StartOS ui app and the public brochure-marketplace marketplace site.
  • shared-libs/ts-modules/start-core/ → @start9labs/start-core — the SDK's core types, ABI, effects interface, and OS bindings (the TS projection of the start-core Rust crate). Consumed directly by web and bundled into @start9labs/start-sdk. Versionless; not published to npm on its own.

App projects defined in the root angular.json (ui, setup-wizard, start-tunnel, start-wrt, brochure-marketplace) reference the two Angular libraries via the TypeScript path mappings in the root tsconfig.json. The libraries also depend on @start9labs/start-core (built from shared-libs/ts-modules/start-core/dist) and patch-db-client (built from shared-libs/crates/patch-db/client).

Data flow

shared-libs/crates/patch-db (first-party)
  ├── core  ──────────────► crates/start-core (Rust)   ──► product binaries
  └── client ─────────────► projects/*/web (Angular)   ──► product web apps
                            shared-libs/ts-modules/*
                                  ▲
shared-libs/ts-modules/start-core/dist ──┘

The Rust backend emits RFC-6902 JSON Patches via patch-db core; the web client applies them via patch-db-client. TypeScript types shared with the backend are generated by ts-rs from start-core.

Further reading

  • README.md — what this directory is and how to use it.
  • AGENTS.md — build/test/format workflow.