what we chose and why.
decisions made during the founding of zarlcorp, with reasoning.
org name: zarlcorp
the evolution of zarldev (personal) into an organization identity. “corp” signals structure and seriousness without being corporate.
repo name: zarlcorp/core
“core” over “platform” or “monorepo” — it’s the foundation everything else builds on.
entity without a face
zarlcorp speaks as an org, not a person. the tools stand on their own merit. no founder story, no personality cult. the work is the identity.
z prefix on packages: keep
brand identity. when you see zsync.ZMap or zcache.Cache in code, you know it’s from the zarlcorp stack. same reason Uber ships zap.
per-module versioning
each package under pkg/ has its own go.mod and version tags. more overhead than a single module, but allows independent release cycles and precise dependency management. idiomatic for a Go multi-module repo.
apps as separate repos, not in the monorepo
clean separation of concerns. each app has its own release cycle. the agent orchestration system is built for multi-repo workflows. core never depends on apps.
TUI-first, not web-first
terminal users are the audience for privacy tools. TUIs are faster to ship, reinforce the manifesto (no browser, no JavaScript, no tracking pixels), and are composable (interactive mode + scriptable flags). web UIs can be added later when earned.
direct Bubble Tea, not a ztui wrapper
the old ztui package wrapped Charmbracelet with custom abstractions that hadn’t earned their complexity. for zarlcorp, use Bubble Tea directly and share only theming/style constants via zstyle. extract higher-level components when patterns emerge across multiple tools.
absorb claude-mngr into core
the orchestration system is foundational infrastructure, not a separate concern. commands, personas, specs, and the manager’s identity belong in the same repo as the packages they produce.
zlog absorbed into zapp
logging setup is an app bootstrap concern. a standalone logging package that just configures slog doesn’t justify its own module. zapp handles it as part of application lifecycle.
strip SeaweedFS from zfilesystem
distributed storage doesn’t fit local-first. the SeaweedFS implementation is removed during migration. OS-backed and in-memory implementations are all that’s needed.
exclude zdocstore
too many issues to migrate (reflection-heavy queries, bubble sort, deprecated APIs, no sentinel errors). rebuild from scratch if a tool needs document storage, informed by what went wrong the first time.
exclude ai package
application-level complexity that doesn’t belong in shared infrastructure. if needed, it becomes its own repo (zarlcorp/zai), not a core package.
exclude zmessagebus and znet from founding set
no founding product needs them yet. add when a tool creates the demand. don’t build infrastructure for hypothetical requirements.
fully open source (MIT)
privacy tools that ask for trust must earn it through transparency. MIT is simple, permissive, and standard in the Go ecosystem.
product priority: zburn → zvault → zshield
zburn is the simplest to build and the most immediately useful. it validates the full stack (core packages → tool → release pipeline → homebrew). zvault builds on the same crypto primitives. zshield requires networking packages that don’t exist yet.
not a competition
zarlcorp doesn’t exist to compete with Pi-hole, Bitwarden, or pass. it exists because these tools should exist in this form — single binary, TUI-first, local-first. self-motivated creation is reason enough.
zapp is a toolkit, not a framework
consumer owns main, owns Run, owns the control flow. zapp provides building blocks (Track, Close, SignalContext) that compose into whatever lifecycle the app needs. no App.Run(func()) callback pattern, no hidden goroutines, no magic. the consumer wires things together explicitly.
sequential LIFO close, not concurrent errgroup
resource cleanup order matters — you close the HTTP server before the database, close the database before the logger. concurrent cleanup via errgroup makes ordering unpredictable. sequential LIFO (last tracked, first closed) gives deterministic teardown. simpler to reason about, easier to debug.