Personal project / 03
Macro
A lightweight Go toolkit for scaffolding consistent services, workers, and jobs, organizing them in workspaces, and standardizing runtime infrastructure without coupling business logic to the framework.
01 / Overview
Overview
Macro is a personal service-toolkit experiment inspired by Go Micro and adapted to Railzway's development conventions. The v0.1.0 CLI focuses on initializing service, worker, and job projects and organizing related projects through a workspace manifest. Its runtime assembles shared infrastructure at the executable boundary while business logic and integrations remain owned by each application.
02 / Architecture
Architecture flow
03 / Problem
Problem
As the number of Go services grows, both project structure and operational conventions tend to drift. Teams repeatedly recreate scaffolding, workspace organization, logging, server startup, shutdown behavior, diagnostics, and database configuration with small but consequential differences. Macro explores how those concerns can be standardized without moving business rules into a framework or generic repository layer.
04 / Technical decisions
Technical decisions
- A deliberately small v0.1.0 CLI centered on init and workspace commands
- Typed YAML manifests as explicit, reviewable project and workspace configuration
- Embedded templates for deterministic scaffolding without network access
- A small lifecycle contract based on Start and Stop rather than a broad framework-owned service abstraction
- An infrastructure-agnostic Worker contract based on Run(context.Context)
- Composition-root wiring so only the executable entrypoint knows every concrete dependency
- Standard gRPC and application-owned protobuf contracts instead of a custom RPC protocol
- Zap logging with an internal HTTP endpoint for changing log levels at runtime
- Loopback-only pprof and management endpoints by default
- Explicit database configuration for PostgreSQL, MySQL, and SQLite rather than opaque DSN-only setup
- GoReleaser and GitHub Actions for reproducible cross-platform CLI releases
05 / Challenges
Challenges
- Keeping generated service, worker, and job layouts consistent without hiding application structure
- Discovering the nearest workspace and storing portable relative project paths
- Keeping convenience APIs small enough that application code remains framework-independent
- Coordinating bounded service shutdown and context-driven worker cancellation correctly
- Defining shared repository primitives without allowing business logic to leak into persistence adapters
- Providing useful defaults while leaving transport and infrastructure choices replaceable
06 / What I learned
What I learned
- A narrow CLI scope makes the first release easier to understand, test, and evolve
- Typed manifests and deterministic templates make project conventions visible instead of implicit
- Worker lifecycle can be standardized without hiding broker-specific semantics
- A service framework is most useful at the composition boundary, not inside business use cases
- Lifecycle management and operational defaults create more consistency than abstracting every application concern
- Repository interfaces should be owned by the application layer and implemented by infrastructure adapters
- Small explicit contracts are easier to test and evolve than framework-wide implicit behavior