architecture

principles

every tool is a single Go binary with a Bubble Tea TUI. no runtime dependencies, no Docker, no databases, no environment variables. download it, run it, done. Homebrew is available for convenience but not required.

data stays on the user’s machine. local storage is files on disk, encrypted at rest with AES-256-GCM and Argon2id key derivation. nothing phones home. nothing syncs to someone else’s server.

each tool is its own repository under zarlcorp/, importing shared packages from zarlcorp/core. tools stay independent. core never depends on tools. when a tool builds something genuinely reusable, it gets extracted into core.

the platform

zarlcorp/core is the shared foundation. every package under pkg/ is an independent Go module with its own go.mod, versioned and released separately.

packages

• zapp — application lifecycle, resource cleanup, signal handling
• zcache — generic caching with pluggable backends
• zcrypto — AES-256-GCM encryption, key derivation, age-compatible file encryption
• zfilesystem — filesystem abstraction with OS and in-memory implementations
• zoptions — generic functional options pattern
• zstyle — Catppuccin Mocha palette, Lipgloss presets, standard keybindings
• zsync — thread-safe map, set, and blocking queue

dependency layers

┌─────────────────────────────────────────────┐
│                   zapp                      │  lifecycle
├──────────────┬──────────────────────────────┤
│   zstyle     │         zcrypto             │  presentation + security
├──────────────┴──────────────────────────────┤
│          zcache  ·  zfilesystem            │  data + storage
├─────────────────────────────────────────────┤
│             zsync  ·  zoptions             │  foundation
└─────────────────────────────────────────────┘

dependencies flow downward only. foundation packages depend on nothing but the standard library.

standard tool structure

zarlcorp/<tool>/
├── cmd/<tool>/          # entrypoint
│   └── main.go
├── internal/            # tool-specific logic
│   ├── tui/             # Bubble Tea models
│   └── ...
├── go.mod               # depends on core/pkg/*
├── Makefile
├── LICENSE
└── README.md

how tools consume core

import "github.com/zarlcorp/core/pkg/zapp"
import "github.com/zarlcorp/core/pkg/zcrypto"
import "github.com/zarlcorp/core/pkg/zstyle"

each package is imported individually. a tool pulls in only what it needs. the go.work file coordinates local development across modules.

release pipeline

each tool follows the same release flow:

1. tag a version → GitHub Actions triggers
2. GoReleaser builds cross-platform binaries
3. binaries published to GitHub Releases
4. Homebrew tap updated (zarlcorp/homebrew-tap)
5. brew install zarlcorp/tap/<tool> works immediately

reusable CI workflows live in zarlcorp/.github — individual tool repos reference them, not copy them.