ak1ra-komj/modular-go

modular-go

Concise guidance for designing Go packages that stay small, focused, and easy to evolve.

Purpose and Triggers

• Use for Go package design, refactoring, and code review.
• Focus on API boundaries, state modeling, and flow decomposition.
• Use when deciding the right abstraction level: local helper, utility package, manager, or builder.
• Prefer explicit boundaries over convenience exports.

Design Principles

1. Every export is a promise — keep the public surface minimal and intentional.
2. One package, one responsibility you can explain in one sentence.
3. Depth over breadth — narrow interfaces that hide rich implementations outlast wide, shallow ones.
4. Stateless by default — treat mutable state as liability that must justify its lifecycle cost.
5. Split along responsibility seams, not file size — every new boundary must earn its indirection cost.
6. Orchestration tells the story; capability methods do the work.
7. Boundaries are translation layers — convert errors, types, and protocols at the edges, not in core logic.
8. Choose the smallest abstraction that solves the real problem; resist premature generalization.
9. Lifecycle is a first-class design concern — design shutdown paths alongside startup paths.

Workflow

1. Define one package responsibility.
2. Expose one obvious primary entry point (type, interface, or function).
3. Keep helpers local by default; extract to xxxutil only for real cross-package reuse.
4. Keep transport handlers focused on protocol mapping and delegate behavior to injected dependencies.
5. Compose orchestration from focused functions, with short stage-intent comments.
6. Re-evaluate boundaries when a package can no longer be explained in one sentence.
7. Re-check against the reference checklists before merge.

Topics

| Topic | Guidance | Reference | | --- | --- | --- | | Module Boundary | Expose minimal API and separate deep vs wide interfaces | references/module-boundary.md | | State Flow | Use stateless functions and one-shot state objects | references/state-flow.md | | Orchestration | Use a single public executor and internal helpers | references/orchestration.md | | gRPC Practices | Keep handlers as thin translators; isolate transport from domain | references/grpc-practices.md | | Review Checklist | Run a fast architecture sanity check before merge | references/review-checklist.md |

References

• Reference files are intentionally short and task-focused.
• Source links are listed in each reference file frontmatter urls.