> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0127 — Package categories, including infrastructure and commerce

> Accepted · 2026-10-20

> [!NOTE]
>
> Amended by [0234](/adr/0234-module-assets-and-storage): the data category gains `assets` and
> `filesystem`, and `stackra gen` (in the developer category) gains the assets collector.

> [!NOTE]
>
> Amends [0028](/adr/0028-package-categories-appear-with-first-package) and
> [0084](/adr/0084-figentra-os-package-port-plan): the category table below replaces the earlier
> one.

> [!NOTE]
>
> Confirmed by [0268](/adr/0268-register-answers-thin-items-r1-to-r18): R5: the categories of this
> ADR are confirmed as they stand. No change.

## Context

Package categories were fixed in the framework round as the FW2 table. The owner accepted it on 2026-10-20 (FW2 a). The
infrastructure category came later, for Pulumi-based infrastructure packages (ADR 0171, not yet on this branch). The owner then
added a `commerce` category for money, ledger and pricing primitives, which closes the placement that was open. Several other
placements were answered question by question. This ADR records the table and the placements, and marks the one open item.

## Decision

1. The package categories are:
   * **foundation:** contracts, validation, errors (ADR 0232, wave 1 part 5);
   * **data:** model, database, content, media, search, state-machine;
   * **application:** actions, ai, ir, registry;
   * **runtime:** outbox, queue, scheduler, workflow, realtime, locking, cache;
   * **communication:** webhooks, notifications, versioning, integrations (assumed, see 5);
   * **security:** connections, entitlements, licensing;
   * **experience:** ui, experience, navigation, console, panel;
   * **developer:** cli, gen, coding-standard, vite-plugin;
   * **cross-cutting:** brand;
   * **commerce:** money, ledger and pricing primitives (owner answer, 2026-10-20). The pricing service and its
     building blocks are placed here as primitives; the service itself is an OS item;
   * **infrastructure:** new. It holds the `@stackra/infra-*` packages defined by 0171.
2. `state` stays a category, because existing packages (settings, feature flags, theming) use it and `AGENTS.md` lists it.
   The FW2 table did not name it. The owner should confirm it (open question 1).
3. The placements the owner set later are fixed: state-machine in data (SM1 placement, mem L405); panel in experience
   (mem L737); coding-standard in developer (mem L566); the Vite plugin is `@stackra/vite-plugin` in developer
   (DX10, mem L567); money and ledger in commerce (owner answer, 2026-10-20).
4. Errors sit in foundation, with `@stackra/errors` (ADR 0232).
5. Integrations sit in communication. This is **assumed**, pending the owner (register Thin list item 6, mem L753).

## Consequences

* The scaffold's category list, the `AGENTS.md` table and the packages guide must match this table. The
  `.agents/rules/workspace-layout.md` rule describes an "infrastructure" category that does not yet exist. That rule
  becomes true with this ADR, and it must add `commerce` and `errors` too. It belongs to `docs-governance`.
* A new package needs one category from this list. A package that fits none is a new ADR, not a new folder.

## Enforcement

planned — `tools/scripts/scaffold.mjs` (`CATEGORIES`) and `tools/scripts/validate-repository.mjs` rejecting a
`packages/<category>` folder that is not in this table.

## Alternatives

* No infrastructure category: the Pulumi packages would sit in developer. The owner chose the separate category (mem L437).
* Money and ledger in data or security: not chosen; the owner chose commerce.

## Supersedes and sources

Supersedes: none.

Amends: [0028](/adr/0028-package-categories-appear-with-first-package) and
[0084](/adr/0084-figentra-os-package-port-plan) (the category lists). Sources: owner questionnaire, framework round
(FW2 a, `stackra-decisions-2026-10-19.md` L339), infrastructure category (L437), placements (L405, L566, L567, L737,
L753), commerce category and errors placement (owner answers, 2026-10-20). Open question: (1) confirm `state`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.