logo hsb.horse

Architecture Decision Record

Tool implementation structure policy

Define routing, feature boundaries, and i18n ownership for adding individual tools.

Accepted #tools #architecture #routing #i18n

Translations

Japanese Portuguese

Tool implementation structure policy

Decision

  • Use src/pages/tools/[category]/[tool-slug]/index.astro as the page entry structure for individual tools.
  • Follow the existing i18n URL strategy by adding src/pages/[lang]/tools/[category]/[tool-slug]/index.astro when localized routes are required.
  • Keep page files thin and move actual implementation into src/features/tools/[tool-slug]/.
  • Keep only shared concerns under src/features/tools/ root, such as catalog loading, slug/category helpers, shared UI, and shared types.
  • Store tool-specific copy in src/features/tools/[tool-slug]/i18n/{lang}.json.
  • Keep src/i18n for site-wide shared copy only.
  • Promote strings to src/i18n only when the same wording is reused by two or more tools or by non-tool pages.
  • Require SoftwareApplication JSON-LD on every tool page.
  • Require a visible breadcrumb trail on every tool page and emit matching BreadcrumbList JSON-LD.

Context

The tools catalog is already managed centrally, while individual tools require independent UI and behavior. We needed a consistent structure that keeps each tool self-contained, avoids a bloated global i18n file, and still preserves shared ownership where appropriate.

Options

  • Option A: Put all tool copy in src/i18n.
  • Option B: Put all tool copy in each tool directory only.
  • Option C: Hybrid ownership (chosen), where tool-local copy is local by default and only truly shared copy is centralized.

Rationale

  • Keeping implementation and copy inside each tool improves locality and reduces coupling.
  • Keeping global i18n focused on site-level copy prevents uncontrolled growth and merge conflicts.
  • The hybrid rule gives a clear migration path for shared text without premature centralization.
  • Thin page-entry files match existing feature/page separation and simplify maintenance.

Consequences

  • Each new tool should include src/features/tools/[tool-slug]/ with implementation and its own i18n/{lang}.json.
  • Page route files under src/pages/.../tools/... should primarily wire params to feature components.
  • Catalog metadata (title and description for listing cards) remains in docs/tools/*.yaml as defined by the existing tools-catalog ADR.
  • Teams must follow the promotion rule for shared strings to keep boundaries clear.
  • Tool page acceptance criteria now include both SoftwareApplication structured data and visible breadcrumbs with BreadcrumbList structured data.