gocell

GoCell

Cell-native Go Engineering Foundation.

GoCell provides Cell/Slice runtime primitives, governance toolchain, and built-in Cells for building reliable Go services with the Slice-Cell architecture.

Quick Start (5 minutes)

git clone https://github.com/ghbvf/gocell.git
cd gocell
go run ./examples/todo-order

Open another terminal:

# Create an order
curl -s -X POST http://localhost:8082/api/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{"item":"my first order"}' | jq .

# List orders
curl -s http://localhost:8082/api/v1/orders | jq .

Check the application logs — you should see event.order.created consumed.

Core Concepts

┌─────────────────────────────────────────────────┐
│  Assembly        (physical deployment unit)      │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐ │
│  │ Cell       │  │ Cell       │  │ Cell       │ │
│  │ ┌────────┐ │  │ ┌────────┐ │  │ ┌────────┐ │ │
│  │ │ Slice  │ │  │ │ Slice  │ │  │ │ Slice  │ │ │
│  │ └────────┘ │  │ └────────┘ │  │ └────────┘ │ │
│  │ ┌────────┐ │  │ ┌────────┐ │  │ ┌────────┐ │ │
│  │ │ Slice  │ │  │ │ Slice  │ │  │ │ Slice  │ │ │
│  │ └────────┘ │  │ └────────┘ │  │ └────────┘ │ │
│  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘ │
│         └───── Contract ─┘───── Contract ┘       │
└─────────────────────────────────────────────────┘

Consistency Levels (L0-L4)

30-Minute Tutorial: Create Your First Cell

Follow these steps to create a custom Cell from scratch.

Step 1: Create Cell directory and metadata

mkdir -p cells/my-cell/slices/myaction

Create cells/my-cell/cell.yaml:

id: my-cell
type: core
consistencyLevel: L1
owner:
  team: my-team
  role: my-owner
schema:
  primary: my_table
verify:
  smoke:
    - my-cell/smoke

Create cells/my-cell/slices/myaction/slice.yaml:

id: myaction
belongsToCell: my-cell
contractUsages:
  - contract: http.my-api.v1
    role: serve
verify:
  unit: myaction/unit
  contract: myaction/contract

Step 2: Define the domain

Create cells/my-cell/internal/domain/model.go:

package domain

type Item struct {
    ID   string
    Name string
}

type ItemRepository interface {
    Create(ctx context.Context, item *Item) error
    GetByID(ctx context.Context, id string) (*Item, error)
}

Step 3: Implement the Cell

Create cells/my-cell/cell.go:

package mycell

import (
    "context"
    "log/slog"
    "github.com/ghbvf/gocell/kernel/cell"
)

type MyCell struct {
    *cell.BaseCell
    logger *slog.Logger
}

func New() *MyCell {
    return &MyCell{
        BaseCell: cell.NewBaseCell(cell.CellMetadata{
            ID: "my-cell", Type: cell.CellTypeCore,
            ConsistencyLevel: cell.L1,
            Owner: cell.Owner{Team: "my-team", Role: "my-owner"},
            Schema: cell.SchemaConfig{Primary: "my_table"},
            Verify: cell.CellVerify{Smoke: []string{"my-cell/smoke"}},
        }),
        logger: slog.Default(),
    }
}

func (c *MyCell) Init(ctx context.Context, deps cell.Dependencies) error {
    return c.BaseCell.Init(ctx, deps)
}

func (c *MyCell) RegisterRoutes(mux cell.RouteMux) {
    mux.Handle("GET /api/v1/hello", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"message":"hello from my-cell"}`))
    }))
}

Step 4: Create a main.go

package main

import (
    "context"
    "os/signal"
    "syscall"

    mycell "github.com/ghbvf/gocell/cells/my-cell"
    "github.com/ghbvf/gocell/kernel/assembly"
    "github.com/ghbvf/gocell/runtime/bootstrap"
)

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    asm := assembly.New(assembly.Config{ID: "my-app", DurabilityMode: cell.DurabilityDemo})
    asm.Register(mycell.New())

    app := bootstrap.New(
        bootstrap.WithAssembly(asm),
        bootstrap.WithHTTPAddr(":8080"),
    )
    app.Run(ctx)
}

Step 5: Build and run

go build ./cmd/my-app && ./my-app
# In another terminal:
curl http://localhost:8080/api/v1/hello
# {"message":"hello from my-cell"}

Example Projects

Runtime Modes

GoCell assemblies must declare a DurabilityMode explicitly (zero value is rejected):

// Production
asm := assembly.New(assembly.Config{ID: "prod", DurabilityMode: cell.DurabilityDurable})

// Development / tests
asm := assembly.New(assembly.Config{ID: "dev", DurabilityMode: cell.DurabilityDemo})

Architecture

├── kernel/       — Cell/Slice runtime + governance tools (framework core)
├── cells/        — Cell implementations (access-core / audit-core / config-core / order-cell / device-cell)
├── contracts/    — Cross-Cell boundary contracts ({kind}/{domain}/{version}/)
├── journeys/     — Journey acceptance specs + status-board.yaml
├── runtime/      — HTTP middleware, auth, worker, observability, bootstrap
├── adapters/     — External system adapters (postgres / redis / rabbitmq / websocket / s3 / oidc)
├── pkg/          — Shared utilities (errcode / ctxkeys / httputil / query)
├── cmd/          — CLI (gocell validate [--strict] / scaffold / generate / check / verify)
├── examples/     — Example projects (sso-bff / todo-order / iot-device)
├── templates/    — Project templates (ADR / cell-design / contract-review / runbook / postmortem / grafana)
└── generated/    — Tool-generated artifacts (indexes, derived views)

Layer Dependencies

kernel/    ← stdlib + pkg/ + gopkg.in/yaml.v3 (no runtime, adapters, cells)
runtime/   ← kernel/ + pkg/ (no cells, adapters)
cells/     ← kernel/ + runtime/ (no adapters — interface decoupling)
adapters/  ← kernel/ + runtime/ + pkg/ + external libs (no cells)
examples/  ← all layers

Built-in Cells

• access-core — Identity management, JWT session lifecycle (RS256), RBAC authorization (7 Slices)
• audit-core — Tamper-proof audit trail with HMAC-SHA256 hash chain (4 Slices)
• config-core — Configuration management with versioning, publishing, and feature flags (5 Slices)

Adapters

Outbox Wiring

The transactional outbox is split across three layers — write at the cell, store + relay loop in runtime/outbox, persistence in adapters/postgres:

// 1. Write inside the cell's business transaction (any package)
postgres.NewOutboxWriter().Write(txCtx, entry)

// 2. Compose the relay at bootstrap (cmd/core-bundle, examples, etc.)
store := postgres.NewOutboxStore(pool.DB())
relay := outbox.NewRelay(store, publisher, outbox.DefaultRelayConfig())
// relay implements worker.Worker — register with bootstrap to manage lifecycle.

runtime/outbox defines the SQL-dialect-neutral Store interface (ClaimPending / MarkPublished / MarkRetry / MarkDead / ReclaimStale / CleanupPublished / CleanupDead / OldestEligibleAt) and the Relay worker that owns the poll / reclaim / cleanup goroutines. Cleanup is data-driven: it sleeps until the next published / dead row crosses its retention window, so an idle table costs zero DB cycles.

Outbox Observability Bridge

For HTTP flows that publish through the transactional outbox, GoCell now bridges request_id, correlation_id, and optional trace_id from handler context into outbox.Entry.Metadata on the PostgreSQL write path. When the event is consumed, ObservabilityContextMiddleware (registered by bootstrap by default) restores those keys into the consumer handler context before business code runs.

For non-bootstrap usage, compose ObservabilityContextMiddleware via SubscriberWithMiddleware manually. To disable consume-side restore, pass WithDisableObservabilityRestore() to bootstrap — the publish-side metadata injection in the outbox writer remains active. When HTTP tracing is enabled, GoCell now extracts inbound traceparent and b3 headers before starting the server span so synchronous service hops preserve the same trace_id. Note: span_id is intentionally excluded across async boundaries — spans do not cross the outbox hop.

Trace Propagation

When HTTP tracing is enabled via WithTracer, GoCell automatically extracts inbound W3C traceparent and B3 headers before starting the server span. W3C takes precedence; B3 is used only as a fallback. Invalid or missing headers safely degrade to a new root trace.

Enablement — tracing is opt-in via bootstrap.WithTracer or router.WithTracer:

// bootstrap (recommended)
tracer := tracing.NewTracer("my-service")  // or adapters/otel.NewTracer(...)
app := bootstrap.New(
    bootstrap.WithAssembly(asm),
    bootstrap.WithHTTPAddr(":8080"),
    bootstrap.WithTracer(tracer),
)

// router (standalone)
r := router.New(router.WithTracer(tracer))

Trust assumption: trace header propagation assumes a trusted-upstream deployment (service-to-service behind a gateway or mesh). Public-facing edges should sanitize or ignore inbound trace headers at the gateway layer. See TRUST-POLICY-01 in docs/backlog.md for the planned public-endpoint strategy.

Framework-emitted consumer logs pick up these fields when the process uses GoCell's context-aware slog handler. This branch does not make plain slog JSON handlers automatically extract request_id, correlation_id, or trace_id. Values restored from broker metadata are validated for safe characters and length before injection into context.

Using in Your Project

# Set up Go private module access
export GOPRIVATE=github.com/ghbvf/gocell

# Add to your project
go get github.com/ghbvf/gocell@latest

Project Templates

GoCell includes templates for common engineering documents:

• templates/adr.md — Architecture Decision Record
• templates/cell-design.md — Cell design document
• templates/contract-review.md — Contract review checklist
• templates/runbook.md — Operations runbook
• templates/postmortem.md — Incident postmortem
• templates/grafana-dashboard.json — Grafana monitoring dashboard

License

MIT