> ## 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.

# 0018 — Framework design record

> Proposed · 2026-10-19

## Context

Earlier repositories made dozens of framework design decisions: how definitions are declared, how bindings are keyed, how
modules compose, how configuration is namespaced. Stackra's framework packages do not exist yet. Copying those decisions
as accepted ADRs would describe packages that are not built, and a standard for nothing teaches people standards are optional.

## Decision

1. **No framework design ADR is written before its package lands.** When a package is created, its design decision is written
   as its own ADR in the same change, and the package's `README.md` links to it.

2. **Until then this page is a reading list**, not a rule. The topics, and where the earlier thinking lives:

   | Topic | Origin |
   | - | - |
   | `define*` factories and the DI boundary | basalt `adr/0037`, `0039` |
   | Keyed bindings instead of a manager base class | basalt `adr/0038` |
   | Module definition, composition and the registry | basalt `adr/0047`, `0048` |
   | Console, pipeline and connector joining the framework tier | basalt `adr/0051`, `0052`, `0053` |
   | Configuration namespaces and templates | figentra `docs/adr/0020-config` |
   | Instance modules, events, application layer | figentra `docs/adr/0017`, `0018`, `0021` |
   | Node entry for full-stack packages | figentra `docs/adr/0029` |
   | i18n, query, router, transport, signals, devtools, logger | figentra `docs/adr/0008` and the named ADRs |
   | Driver packages | basalt `plans/driver-packages` |
   | AI inside the application layer, not a fifth layer | basalt `adr/0026` |

3. **Product compiler and definition-tier designs are out of scope** for Stackra.

## Consequences

* The ADR index stays honest about what is built.
* Writing a package's ADR becomes part of creating the package.

## Enforcement

Planned: the package scaffold (`pnpm new package`) prompts for the ADR link in the new package's `README.md`; the `architecture-guardian` agent blocks a new framework package without one.

## Supersedes and sources

Supersedes: none. Sources as listed in the table; the origin repositories are informational only.


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