Internal Package Building Skill

Internal Package Building Skill

Use this skill when creating or refactoring internal Go packages.

When to create a new package

• New domain → new directory under internal/ (e.g. new feature area or bounded context).
• Existing domain → add or edit files in the existing package; do not split without a clear boundary.
• Shared cross-cutting concern (DB, config, models) → use or extend existing shared packages (internal/​db, internal/​models, internal/​env) rather than creating a new one unless the concern is clearly separate.

Layout

• One package per directory; package name = directory name (e.g. internal/​candidate_tree → package candidate_tree).
• Entrypoints live only in cmd/​ (e.g. cmd/​api, cmd/​evaluator, cmd/​importer). All shared logic lives in internal/​.
• internal/​ must not import cmd/​; cmd packages wire and call internal packages.

Imports

• Import internal packages by module path: tarkov-build-optimiser/​internal/<pkg>
• Example: import "tarkov-build-optimiser/​internal/​models"

Existing internal packages (use, don’t duplicate)

Checklist for a new internal package

1. Create internal/<name>/ with at least one .go file; package name = <name>.
2. Add only code that belongs to that domain; put shared DB/​config in internal/​db or internal/​env.
3. Import other internal packages via tarkov-build-optimiser/​internal/​....
4. Keep the package focused; if it grows into two clear domains, consider splitting into two packages only when the boundary is obvious.
5. Add tests in the same package (*_test.go); use *_unit_test.go or *_integration_test.go per project conventions.

Boundaries to respect

• No business logic in cmd/​ — cmd only parses flags/​env, opens DB, and calls internal packages.
• No circular imports — internal packages may depend on each other only acyclically; if you introduce a cycle, extract a shared type or helper into a lower-level package.
• Database access — use internal/​db for connections and internal/​models for SQL and data types; do not add new ad-hoc DB packages.