@forgrit/blueprint

App-spec format and blueprint helpers for the ForGrit Foundry OS — route trees, sections, archetypes, deterministic hashing, and IA planning primitives.

Status: v0.1.0 (early access). API surface may change in v0.2.0.

Install

npm install @forgrit/blueprint
# or
pnpm add @forgrit/blueprint
# or
yarn add @forgrit/blueprint

Requires Node.js >=20.0.0.

Quick start — pure helpers

The pure helpers have zero runtime dependencies and work in any TS/JS project.

import { computeContractHash, computeBlueprintHash, diffBlueprints } from '@forgrit/blueprint';

const blueprint = {
  /* your blueprint object */
};
const hashA = computeBlueprintHash(blueprint);

const updated = {
  /* modified blueprint */
};
const hashB = computeBlueprintHash(updated);

const diff = diffBlueprints(blueprint, updated);
console.log({ same: hashA === hashB, diff });

Quick start — NestJS module

BlueprintModule wires up the BlueprintService, the workers, and the ArchitectureDecisionsController. It depends on Symbol-token providers for the platform infrastructure (Prisma, logger, queue, jobs) — see "DI binding" below.

import { Module } from '@nestjs/common';
import { BlueprintModule } from '@forgrit/blueprint';
import { MyPlatformProvidersModule } from './platform';

@Module({
  imports: [MyPlatformProvidersModule, BlueprintModule],
})
export class AppModule {}

API surface

| Category | Examples | NestJS needed? | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------- | | Pure functions (hash, diff, validators) | computeContractHash, computeBlueprintHash, diffBlueprints, extractCodegenHints, validateIaPlan | No | | Rules engines (classes, no DI) | IaRulesEngine, ArchitectureRulesEngine, ContractRulesEngine | No | | Static registries | FieldCatalog, ScreenLibrary, SectionLibrary, SUPPORTED_LOCALES | No | | NestJS services + module | BlueprintModule, BlueprintService, BlueprintWorker, ArchitectureBlueprintWorker, ArchitectureDecisionsController | Yes | | Type-only exports | BlueprintDiff, ScreenDiff, DbField, ApiSurface, BlueprintCodegenHints, IaVariant, FeatureRule, DomainPool | No (erased) | | Runtime helpers | mergeFigmaEntitiesIntoRequirements, classifyFeatureIntent, deriveDeterministicCreatedAt | No |

DI binding (NestJS consumers only)

If you import BlueprintModule, you MUST provide these 5 Symbol tokens somewhere in your app's provider tree. They abstract the platform infrastructure so @forgrit/blueprint itself stays platform-agnostic.

import { Module } from '@nestjs/common';
import {
  PRISMA_SERVICE,
  LOGGER_SERVICE,
  QUEUE_SERVICE,
  JOBS_SERVICE,
  JOB_STEP_SERVICE,
} from '@forgrit/blueprint';
import { MyPrismaService } from './prisma';
import { MyLoggerService } from './logger';
import { MyQueueService } from './queue';
import { MyJobsService } from './jobs';
import { MyJobStepService } from './job-step';

@Module({
  providers: [
    { provide: PRISMA_SERVICE, useClass: MyPrismaService },
    { provide: LOGGER_SERVICE, useClass: MyLoggerService },
    { provide: QUEUE_SERVICE, useClass: MyQueueService },
    { provide: JOBS_SERVICE, useClass: MyJobsService },
    { provide: JOB_STEP_SERVICE, useClass: MyJobStepService },
  ],
  exports: [PRISMA_SERVICE, LOGGER_SERVICE, QUEUE_SERVICE, JOBS_SERVICE, JOB_STEP_SERVICE],
})
export class MyPlatformProvidersModule {}

The interfaces each token implements are re-exported from @forgrit/blueprint so you can type your services correctly. See IPrismaService, ILoggerService, IQueueService, IJobsService, IJobStepService for the contracts.

Versioning

See CHANGELOG.md for the full history. The v0.x line is early access — breaking changes may land between minor versions. From v1.0.0 onwards, this package follows strict Semantic Versioning.

License

MIT — Copyright (c) 2026 ForGrit AI.

Links

• Homepage: https://github.com/forgrit-ai/forgrit/tree/main/lifecycle/2-planning/blueprint
• Issues: https://github.com/forgrit-ai/forgrit/issues
• ForGrit Foundry OS: the consolidation spec at docs/superpowers/specs/2026-05-24-foundry-os-consolidation.md