Repository Structure Specification

This document defines the recommended repository layout for implementing OrbitMesh with:

1. Goal

This document defines the recommended repository layout for implementing OrbitMesh with:

Go Kratos Control Plane.
Cloudflare Workers Install Service.
Go standalone Edge Runtime.
Next.js Console deployed on Cloudflare Pages.
Public website reserved under apps/web.
Shared domain and API contracts.

2. Recommended Repository

orbitmesh/
  services/
    control-plane/
      api/
        buf.yaml
        buf.gen.yaml
        orbitmesh/
          v1/
            common.proto
            errors.proto
            auth.proto
            tenant.proto
            node.proto
            capability.proto
            runtime.proto
            endpoint.proto
            deployment.proto
            desired_state.proto
            traffic_policy.proto
            subscription.proto
            health.proto
            edge_runtime.proto
      cmd/
        orbitmesh-api/
          main.go
      internal/
        biz/
          auth/
          tenant/
          node/
          capability/
          runtime/
          endpoint/
          deployment/
          desiredstate/
          trafficpolicy/
          subscription/
          health/
          billing/
        data/
          postgres/
          redis/
        server/
          http.go
          grpc.go
        service/
        conf/
        middleware/
        compiler/
        event/
      ent/
        schema/
      configs/
      Dockerfile
    install/
      src/
      scripts/
      wrangler.toml
      package.json

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

  apps/
    console/
      app/
      components/
      lib/
      hooks/
      public/
      next.config.ts
      package.json
    platform/
      app/
      components/
      lib/
      hooks/
      public/
      next.config.ts
      package.json
    web/
      app/
      components/
      lib/
      hooks/
      public/
      next.config.ts
      package.json

  packages/
    domain/
    proto/
    api-client/
    ui/

  deployments/
    docker-compose/
    systemd/

  docs/
  scripts/

3. Control Plane Structure

The Control Plane uses Kratos conventions:

api/       Protobuf API definitions
cmd/       service entrypoint
internal/service/  transport handlers
internal/biz/      use cases and domain logic
internal/data/     repositories and database adapters
internal/server/   HTTP/gRPC server bootstrap
internal/conf/     config definitions

MVP remains a modular monolith. Do not split into microservices initially.

4. Control Plane Boundaries

services/control-plane owns:

Tenant Console API.
Edge Runtime API.
Node lifecycle.
Capability binding lifecycle.
Runtime binding lifecycle.
Endpoint lifecycle.
Deployment token lifecycle.
Desired State generation.
Configuration compilation.
Traffic Policy evaluation.
Subscription distribution.
Health aggregation.
Billing and entitlement checks.

It must not:

Proxy user traffic.
SSH into nodes.
Store plaintext tokens.

5. Install Service Boundaries

services/install owns:

install.orbitmesh.dev.
pathless public installer entrypoint.
serving generated installer shell scripts from Cloudflare Workers.

It must not:

own tenant state.
create deployment tokens.
compile Desired State.
proxy artifact downloads from downloads.orbitmesh.dev.

Installer source remains services/install/install.sh; the Worker embeds a generated TypeScript module from that source.

6. Edge Runtime Boundaries

edge-runtime owns:

Registration.
Heartbeat.
Desired State pull.
Runtime config apply.
Runtime process management.
Health probes.
Local rollback.

It should be a small Go binary. It may use generated API clients, but should not import Kratos server framework.

7. Console Boundaries

apps/console owns tenant-console workflows:

tenant Console UI.
Login flow.
Node pages.
Deployment token page.
Traffic Policy editor.
Subscription page.
Health and observability views.
tenant plan display and tenant quota state.
read-only tenant-facing runtime catalog views.

It must call Control Plane APIs over HTTP.

It should not:

Connect directly to PostgreSQL.
Generate RuntimeConfiguration.
Talk directly to Edge Runtime.
Manage platform plan catalog, plan versions, or plan terms.
Assign, suspend, or expire tenant plan subscriptions as a platform operator.
Manage platform-owned node, relay, egress, DNS, certificate, runtime catalog, or subscription target resources.

apps/platform owns platform-operator workflows:

plan catalog, plan versions, and plan terms.
tenant plan subscription lifecycle.
managed node and platform relay/egress resource pools.
global runtime catalog and install profile administration.
subscription target catalog administration.
system domains, ACME, DNS providers, and certificates.
platform audit, support, diagnostics, and operational configuration.

apps/web is reserved for the public website and documentation landing pages. It must not own Console workflows.

8. Shared Packages

packages/domain defines common resource types:

Tenant.
Node.
CapabilityBinding.
RuntimeBinding.
Endpoint.
Subscription.
DesiredState.
RuntimeConfiguration.
TrafficPolicy.
Subscription.

packages/proto contains generated protobuf code where sharing is useful.

packages/api-client contains generated or hand-written typed clients for the Tenant Console, Platform Console, and Edge Runtime.

Avoid importing Control Plane internals into Edge Runtime.

Avoid putting persistence models in shared packages. Database models belong to services/control-plane/internal/data.

9. MVP Package Order

Recommended implementation order:

services/control-plane/internal/conf
services/control-plane/internal/data
services/control-plane/internal/biz/node
services/control-plane/internal/biz/capability
services/control-plane/internal/biz/runtime
services/control-plane/internal/biz/endpoint
services/control-plane/internal/biz/deployment
edge-runtime/internal/client
edge-runtime/internal/adapter/singbox
services/control-plane/internal/compiler
services/control-plane/internal/biz/trafficpolicy
services/control-plane/internal/biz/subscription
apps/console

10. Naming Conventions

Use domain terms consistently:

node for host or device resources.
capability binding for enabled product roles.
runtime binding for concrete runtime instances.
traffic.entry / traffic.exit for Traffic role values.
edge-runtime for node-side runtime concepts.
traffic-policy for policy decisions.
configuration-compiler for Desired State compilation.
subscription for Traffic client-facing configuration distribution.
tenant subscription for billing subscriptions.