Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Engineering Specs

ENGINEERING SPECS

Engineering Scaffold Specification

This document defines the initial engineering scaffold for implementing OrbitMesh.
View source

1. Goal

This document defines the initial engineering scaffold for implementing OrbitMesh.

It covers:

  • repository bootstrap order.
  • required toolchain.
  • Makefile targets.
  • protobuf generation.
  • Ent schema conventions.
  • environment loading.
  • local development commands.
  • generated code rules.

2. Bootstrap Order

Create the implementation repository in this order:

  1. initialize root go.work.
  2. create services/control-plane.
  3. promote proto drafts from docs/api/proto.
  4. create Control Plane Kratos app.
  5. add Ent schema and migration entrypoint.
  6. create edge-runtime.
  7. create apps/console.
  8. add Docker Compose local dependencies.
  9. add CI.

Do not start with microservices. The Control Plane starts as a modular monolith.

3. Root Layout

orbitmesh/
  Makefile
  go.work
  .env.example
  .gitignore

  services/
    control-plane/
    install/

  edge-runtime/

  apps/
    console/
    web/

  packages/
    proto/
    api-client/
    ui/

  deployments/
    docker-compose/
    systemd/

  docs/

During the documentation stage, docs is the source.

4. Toolchain

Required:

Go 1.24+
Node.js 22+
pnpm 9+
Docker
Docker Compose
buf
protoc-gen-go
protoc-gen-go-grpc
protoc-gen-go-http
protoc-gen-openapi
Ent

Recommended installation targets:

make tools
make tools-go
make tools-web

Tool versions should be pinned in:

services/control-plane/tools.go
apps/console/package.json

5. Makefile Targets

Top-level targets:

.PHONY: tools proto openapi api-client migrate test lint typecheck
.PHONY: dev-control-plane dev-edge-runtime dev-console docker-up docker-down

tools:
	$(MAKE) tools-go
	$(MAKE) tools-web

proto:
	cd services/control-plane/api && buf generate

openapi:
	cd services/control-plane/api && buf generate --template buf.gen.yaml

api-client:
	cd packages/api-client && pnpm generate

migrate:
	cd services/control-plane && go run ./cmd/migrate

test:
	go test ./...

lint:
	go vet ./...
	cd apps/console && pnpm lint

typecheck:
	cd apps/console && pnpm type-check

dev-control-plane:
	cd services/control-plane && go run ./cmd/orbitmesh-api

dev-edge-runtime:
	cd edge-runtime && go run ./cmd/orbitmesh --help

dev-console:
	cd apps/console && pnpm dev

docker-up:
	docker compose -f deployments/docker-compose/docker-compose.yml up -d

docker-down:
	docker compose -f deployments/docker-compose/docker-compose.yml down

Rules:

  • targets should work from repository root.
  • targets should not require global environment other than installed tools.
  • generated files must be reproducible.
  • make test must not require external cloud services.

6. Go Workspace

Recommended go.work:

go 1.24.0

use (
  ./services/control-plane
  ./edge-runtime
)

Control Plane module:

module github.com/orbitmesh-official/orbitmesh/services/control-plane

Edge Runtime module:

module github.com/orbitmesh-official/orbitmesh/edge-runtime

Shared Go packages should be added only when there is a concrete cross-module need.

7. Proto Setup

Implementation path:

services/control-plane/api/
  buf.yaml
  buf.gen.yaml
  orbitmesh/
    v1/
      *.proto

Source during docs stage:

docs/api/proto/

Generation output:

services/control-plane/api/orbitmesh/v1/*.pb.go
services/control-plane/api/orbitmesh/v1/*_grpc.pb.go
services/control-plane/api/orbitmesh/v1/*_http.pb.go
docs/api/generated/
packages/api-client/

Rules:

  • protobuf files are edited manually.
  • generated files are not edited manually.
  • breaking changes require explicit version decision.
  • Edge Runtime API changes must be compatible with at least one previous minor release after P0.

8. Control Plane Scaffold

Initial Kratos layout:

services/control-plane/
  api/
  cmd/
    orbitmesh-api/
      main.go
    migrate/
      main.go
  ent/
    schema/
  internal/
    service/
    biz/
    data/
    server/
    conf/
    middleware/
    compiler/
    event/
  configs/
  Dockerfile
  go.mod

Implementation order:

  1. internal/conf.
  2. internal/server.
  3. ent/schema.
  4. internal/data.
  5. internal/biz/auth.
  6. internal/biz/deployment.
  7. internal/biz/node.
  8. internal/biz/capability.
  9. internal/biz/runtime.
  10. internal/biz/endpoint.
  11. internal/biz/subscription.
  12. internal/biz/desiredstate.
  13. internal/compiler.
  14. internal/service.

9. Edge Runtime Scaffold

Initial layout:

edge-runtime/
  cmd/
    orbitmesh/
      main.go
    orbitmeshd/
      main.go
  internal/
    adapter/
      singbox/
      fake/
    client/
    config/
    health/
    identity/
    installer/
    metrics/
    runtime/
    state/
    supervisor/
  packaging/
    systemd/
  go.mod

Implementation order:

  1. config loader.
  2. local identity store.
  3. Control Plane API client.
  4. request signer.
  5. register command.
  6. heartbeat loop.
  7. desired state sync loop.
  8. fake runtime adapter.
  9. sing-box runtime adapter.
  10. rollback.

10. Console Scaffold

Initial layout:

apps/console/
  app/
    (console)/
      nodes/
      nodes/enroll/
      traffic/subscriptions/
      traffic/policies/
      traffic/usage/
      network/endpoints/
      network/domains/
      runtime-catalog/
      settings/
    login/
  components/
    console/
    ui/
  lib/
    api-client.ts
    auth.ts
    env.ts
  hooks/
  package.json

apps/platform/
  app/
    plans/
    tenants/
    managed-nodes/
    runtime-catalog/
    subscription-targets/
    domains/
    certificates/
    audit/
  components/
  lib/
  hooks/
  package.json

Rules:

  • Tenant Console calls Control Plane APIs through lib/api-client.ts.
  • no direct PostgreSQL access.
  • no Control Plane business logic in Next.js route handlers.
  • route handlers are only for frontend-owned utilities.

11. Environment Files

Root .env.example:

ORBITMESH_DATABASE_URL=postgres://orbitmesh:orbitmesh@localhost:5432/orbitmesh?sslmode=disable
ORBITMESH_DATABASE_DRIVER=pgx
ORBITMESH_REDIS_ADDR=localhost:6379
ORBITMESH_REDIS_PASSWORD=
ORBITMESH_REDIS_URL=
ORBITMESH_PUBLIC_URL=http://localhost:8080
ORBITMESH_INSTALL_ENDPOINT_URL=https://install.orbitmesh.dev
ORBITMESH_EDGE_RUNTIME_DOWNLOAD_PREFIX=https://downloads.orbitmesh.dev/edge-runtime/latest
ORBITMESH_JWT_SECRET=change-me
ORBITMESH_DEPLOYMENT_TOKEN_TTL=1800s
ORBITMESH_LOG_LEVEL=debug

NEXT_PUBLIC_ORBITMESH_API_URL=http://localhost:8080
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change-me

Edge Runtime local env:

ORBITMESH_CONTROL_PLANE_URL=http://localhost:8080
ORBITMESH_NODE_ID=
ORBITMESH_EDGE_RUNTIME_ID=
ORBITMESH_LOG_LEVEL=debug

Rules:

  • production secrets are never committed.
  • .env.local is ignored.
  • Control Plane config can read environment variables and optional YAML config.
  • duration environment values use protobuf duration syntax, for example 1800s.
  • Edge Runtime production config comes from /etc/orbitmesh/edge-runtime.yaml.

12. Ent Schema Conventions

Schema source:

services/control-plane/ent/schema/

Generated code:

services/control-plane/ent/

Rules:

  • Ent schema is the source of truth for P0 database structure.
  • make ent-generate regenerates Ent code.
  • make migrate applies Ent schema migration to the configured local SQL database through Schema.Create.
  • destructive schema changes require an explicit review before enabling drop options.
  • data backfills and corrections must be implemented as separate one-off commands.
  • every tenant-scoped table has tenant_id.
  • token columns store hashes only.
  • created_at and updated_at use timestamptz.

13. Generated Code Rules

Generated code directories:

services/control-plane/api/
packages/api-client/

Rules:

  • generated files must include generator version in header when possible.
  • do not manually edit generated files.
  • generated code changes must be reviewed with source proto changes.
  • CI must fail if generated code is stale.

14. Logging and Request IDs

Control Plane:

  • every request has request_id.
  • logs include tenant_id when available.
  • Edge Runtime APIs include node_id.
  • secret values are redacted.

Edge Runtime:

  • logs include node_id, runtime_binding_id, loop, desired_state_version, runtime, status.
  • logs must not include deployment token, device private key, runtime password, or full subscription URL.

15. Local Fake Runtime

The fake runtime adapter is required for P0 tests.

Behavior:

  • Validate succeeds unless config contains a test failure marker.
  • Apply stores config in memory or temp directory.
  • Reload records invocation count.
  • Status returns configured fake status.

Use cases:

  • CI E2E without sing-box.
  • rollback tests.
  • apply result tests.

16. CI Scaffold

Initial CI stages:

proto lint
proto breaking check
go test
go vet
Ent schema generation check
openapi validation
web lint
web typecheck
fake runtime e2e

CI should not require:

  • paid cloud credentials.
  • real VPS.
  • Cloudflare Pages deployment.
  • external API access.

17. Commit Boundaries

Recommended implementation commit order:

  1. repository scaffold.
  2. proto contracts and generated code.
  3. Ent schema and persistence.
  4. Control Plane boot and health endpoint.
  5. auth and tenant.
  6. deployment token.
  7. Edge Runtime register.
  8. heartbeat.
  9. DesiredState and compiler.
  10. fake runtime E2E.
  11. sing-box adapter.
  12. Tenant Console shell.
OrbitMesh DocumentationContent follows the repository's main branch.