Skip to content

v0.5: Layered architecture redesign #197

Open

Description

@Loongphy

Summary

Tracking issue for the layered-architecture redesign audited post-0.3.x. The current layout has three grab-bag directories (cli/ 40 files, workflows/ 28, api/ 15) with blurred boundaries, two real dependency-direction violations, and facade re-export files that silently accumulate dead aliases (two cleanup rounds already merged: #192, #194).

Target layering (one-directional imports only):

L0 core/         runtime, io_util, compat_fs (std only)
L1 domain/       auth, registry, session — pure state & storage
L2 net/          transport port + http_* adapters + endpoint modules
L2.5 proto/      cross-layer contracts: results DTOs, query model, daemon outcome, targets
L3 ui/           command parsers, output/JSON, picker, live screens, widgets (cli+tui merge candidate)
L4 app/          command orchestrators 1:1 with CLI verbs + live subsystem + internal services
L5 main.zig

Task list

  • Facade guard in CI — script that fails on dead const X = mod.Y aliases and dangling re-exports (prevents the third rot recurrence; cheap alternative to collapsing 300+ registry.X call sites)
  • Extract proto/ — move workflows/{results,query,targets}.zig + split the Outcome enum out of codex_daemon.zig; kills the 3 cli→workflows back-edges (json_output→results, completion→query, output→codex_daemon)
  • Move autoImportActiveAuth out of registry/ into the app layer — kills the L1→L2 violation, registry becomes pure storage
  • Split workflows/ into commands/ (13 orchestrators, 1:1 with CLI verbs + dispatch), live/ (refresh subsystem), internal/ (preflight, account_names, usage, active_auth, legacy_background, codex_daemon)
  • Relocate env.zig — file only holds nowMilliseconds/nowSeconds; belongs in time/ or core/
  • compat_fs — annotate as test-support or move under tests/support/ (production code already uses std.Io directly)
  • (optional, last) Directory renames: workflows→app, api→net, cli+tui→ui, auth+session→domain/ — pure import-path churn, do only after structural fixes land

Notes:

  • Keep every PR independently mergeable — main stays releasable at all times.
  • registry/ is the best-organized directory today; leave its internals alone.
  • Zig lazy compilation makes dead decls and dangling re-exports invisible — the guard script is what keeps the new structure honest.

Activity

  1. added this to the v0.5 milestone on Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions