Architecture Notes

This document defines contributor-facing architecture boundaries for the monorepo.

Composition Responsibilities

• detection.ts
  • Reads project signals (package.json, tsconfig presence, GraphQL schema files).
  • Produces detected options (detectedFrameworks, runtime, integrations, preset hints).
  • Must stay side-effect free beyond filesystem reads.
• resolvers.ts
  • Resolves preset defaults and framework inputs.
  • Accepts installed optional framework flags (true) and imported config arrays/factories.
• index.ts
  • Composes final flat-config order.
  • Applies merge strategy, framework dependencies, integrations, and strict mode.
  • Keeps final ordering contract: core -> frameworks -> TypeScript -> integrations -> Prettier.
• integrations.ts
  • Loads only the installed feature-pack registries required by the selected categories.
  • Resolves the shared ConfigFeature contract without importing plugin implementations into the composer.
• feature.ts
  • Defines the ecosystem-neutral feature adapter contract.
  • Sorts selected features and separates normal configs from finalizers such as Prettier.
• Feature packs (packages/extensions, packages/formats, packages/libraries, packages/testing, and packages/tools)
  • Own their plugin dependencies, public factories, and feature registries.
  • Keep adding one category from installing unrelated categories.
• packages/integrations
  • Is a compatibility aggregate over the five feature packs.
  • Does not own plugin implementations.

Data Flow

1. detectProjectOptions() infers defaults.
2. resolvePreset() provides preset defaults.
3. defineConfig() merges detected + preset + explicit options.
4. Frameworks are resolved through resolveFramework().
5. Selected feature-pack registries are resolved through getIntegrationConfigs().
6. Prettier is appended last via getPrettierConfig().
7. Strict mode is applied at the end with applyStrictMode().

Contract Rules

• types.ts is the single source of truth for enums and option types.
• New enum values require mapping updates in:
  • the matching feature pack registry,
  • resolvers.ts (presets when applicable),
  • integration tests under packages/tests/src/.
• Feature adapters must use globally stable order values. Prettier and other final overrides use the finalizer phase.
• Detection precedence must remain deterministic:
  • Worker > Node > Browser > Universal.
• Framework implication rules (for example, next and expo imply react) must stay covered by tests.

Documentation Governance

Docs lifecycle policy for current docs and the frozen version archives lives in:

• DOCS_GOVERNANCE.md