Module Scaffold

The CLI provides scaffolding commands to quickly create new modules with the correct structure and boilerplate code.

Creating a New Module

Basic Module

tinysystems init my-module

This creates a new module with:

my-module/
├── cmd/
│   └── main.go              # Entry point
├── components/              # Component directory
├── go.mod                   # Go module
├── go.sum
├── Dockerfile              # Container build
├── Makefile                # Common tasks
├── .tinysystems.yaml       # CLI config
└── README.md               # Documentation

With Go Module Path

tinysystems init my-module --go-module github.com/myorg/my-module

From Template

# List available templates
tinysystems init --list-templates

# Use specific template
tinysystems init my-module --template advanced

Project Structure

cmd/main.go

package main

import (
    "github.com/tiny-systems/module/module"
    "github.com/myorg/my-module/components/example"
)

func main() {
    mod := module.NewWithComponents(
        &example.Component{},
    )

    if err := mod.Run(); err != nil {
        panic(err)
    }
}

Dockerfile

# Build stage
FROM golang:1.21-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o module ./cmd/main.go

# Runtime stage
FROM alpine:3.18

WORKDIR /app
COPY --from=builder /app/module .

ENTRYPOINT ["/app/module"]

Makefile

.PHONY: build run test lint

MODULE_NAME := my-module
VERSION := $(shell git describe --tags --always --dirty)
REGISTRY := my-registry.io

build:
	go build -o bin/module ./cmd/main.go

run:
	go run ./cmd/main.go

test:
	go test -v ./...

lint:
	golangci-lint run

docker-build:
	docker build -t $(REGISTRY)/$(MODULE_NAME):$(VERSION) .

docker-push: docker-build
	docker push $(REGISTRY)/$(MODULE_NAME):$(VERSION)

generate:
	go generate ./...

helm-package:
	helm package charts/$(MODULE_NAME)

.tinysystems.yaml

module:
  name: github.com/myorg/my-module
  version: 1.0.0
  description: My custom module

build:
  registry: my-registry.io
  image: my-module

development:
  port: 50051
  namespace: tinysystems-dev
  watch:
    - "**/*.go"
    - "!**/*_test.go"

deployment:
  namespace: tinysystems
  replicas: 2
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

Adding Components

Generate Component

cd my-module
tinysystems generate component transformer

Creates:

components/transformer/
├── component.go       # Main implementation
├── types.go          # Type definitions
└── component_test.go # Tests

Register Component

Update cmd/main.go:

package main

import (
    "github.com/tiny-systems/module/module"
    "github.com/myorg/my-module/components/example"
    "github.com/myorg/my-module/components/transformer"
)

func main() {
    mod := module.NewWithComponents(
        &example.Component{},
        &transformer.Component{},  // Add new component
    )

    if err := mod.Run(); err != nil {
        panic(err)
    }
}

Template Types

Basic Template

Minimal module with one example component:

tinysystems init my-module --template basic

• Single component example
• Minimal configuration
• Basic Dockerfile

Advanced Template

Full-featured module setup:

tinysystems init my-module --template advanced

• Multiple component examples
• GitHub Actions CI/CD
• Helm chart
• Comprehensive documentation

Server Template

For HTTP-serving modules:

tinysystems init my-api --template server

• HTTP server component
• Ingress configuration
• Health endpoints
• TLS setup

Customizing Scaffolds

Custom Templates

Create .tinysystems/templates/ in your home directory:

~/.tinysystems/templates/
├── myorg-basic/
│   ├── template.yaml
│   ├── cmd/main.go.tmpl
│   └── components/example/component.go.tmpl

Use with:

tinysystems init my-module --template myorg-basic

Template Variables

Templates support Go template syntax:

// component.go.tmpl
package {{.ComponentName}}

import (
    "github.com/tiny-systems/module/module"
)

type Component struct{}

func (c *Component) GetInfo() module.Info {
    return module.Info{
        Name:        "{{.ComponentName | kebab}}",
        Description: "{{.Description}}",
    }
}

Best Practices

1. Use Meaningful Names

# Good
tinysystems init data-transformer
tinysystems generate component csv-parser

# Avoid
tinysystems init module1
tinysystems generate component comp

2. Organize by Feature

components/
├── input/        # Input-related components
│   ├── http-receiver/
│   └── file-reader/
├── transform/    # Transformation components
│   ├── json-parser/
│   └── filter/
└── output/       # Output components
    ├── http-sender/
    └── file-writer/

3. Include Tests

Always generate tests with components:

tinysystems generate component my-component
# Includes component_test.go

4. Document Components

Add README.md to each component:

components/transformer/
├── component.go
├── types.go
├── component_test.go
└── README.md    # Document purpose, usage, examples

Next Steps

• Local Testing - Test your module
• Development Commands - CLI reference
• Building Modules - Build for production