Technical Reference

Architecture

How Blocks validates your code at development time

Spec → Validate → Ship

Define your domain rules. AI writes code. Blocks checks it. Fix drift or update spec. Repeat until aligned.

blocks.yml→blocks run→ship

01Monorepo Structure

@blocksai/cli

Command-line interface for running validations

@blocksai/schema

Parses and validates blocks.yml configuration

@blocksai/domain

Domain modeling, entities, and static analysis

@blocksai/validators

Schema, Shape, and Domain validator implementations

@blocksai/ai

Multi-provider AI abstraction (OpenAI, Anthropic, Google)

Dependency Flow

cli→validators→domain→schema|validators→ai

02Validation Pipeline

Schema Validator

schema.io

Fast

Validates input/output signatures match blocks.yml

All inputs have name and typeAll outputs have name and typeTypes match entity definitions

Shape Validator

shape.exports.ts

Fast

Validates file structure and TypeScript exports

Required files exist (index.ts, block.ts)TypeScript exports are presentEntry points properly defined

Domain Validator

domain.validation

AI-powered

Semantic validation against domain rules using AI

Philosophy adherenceSemantic HTML complianceDomain rule violationsCode quality patterns

blocks.yml

ValidationResult[]

03AI Integration

Context Sent to AI

→Project philosophy from blocks.yml
→Domain entities and semantics
→ALL source files in block directory
→Domain rules (global + block-specific)
→Validation instructions

Excluded

node_modules/dist/build/.git/coverage/

Supported Providers

OpenAIgpt-4o, gpt-4o-mini

Anthropicclaude-3-5-sonnet, claude-3-5-haiku

Googlegemini-1.5-pro, gemini-1.5-flash

04Configuration

# blocks.yml
$schema: "blocks/v2"
name: "my-project"

philosophy:
  - "Use semantic HTML tags"
  - "Accessibility is required"

validators:
  - schema
  - shape
  - name: domain
    config:
      rules:
        - id: no_inline_styles

blocks:
  theme.modern:
    path: blocks/theme-modern
    inputs:
      - name: data
        type: object