🤖 AI Blueprint Guide

Complete reference for AI agents to create blueprints automatically

This guide provides everything an AI agent needs to create sophisticated, production-ready blueprints that follow Architech best practices.

📋 TABLE OF CONTENTS

🔧 BLUEPRINT ACTIONS REFERENCE

Action Types Overview

The Architech supports 15 blueprint action types. Each action has specific parameters and use cases.

Action Type	Purpose	File Types	Complexity
`CREATE_FILE`	Create new files	Any	Simple
`ENHANCE_FILE`	Modify existing files	Any	Advanced
`INSTALL_PACKAGES`	Install npm packages	package.json	Simple
`ADD_SCRIPT`	Add npm scripts	package.json	Simple
`ADD_ENV_VAR`	Add environment variables	.env	Simple
`APPEND_TO_FILE`	Append content to files	Any	Simple
`PREPEND_TO_FILE`	Prepend content to files	Any	Simple
`RUN_COMMAND`	Execute shell commands	-	Medium
`MERGE_JSON`	Merge JSON objects	.json	Medium
`ADD_TS_IMPORT`	Add TypeScript imports	.ts, .tsx	Medium
`ADD_DEPENDENCY`	Add dependencies	package.json	Simple
`ADD_DEV_DEPENDENCY`	Add dev dependencies	package.json	Simple
`MERGE_CONFIG`	Merge configuration files	Any	Advanced
`WRAP_CONFIG`	Wrap configuration	Any	Advanced
`EXTEND_SCHEMA`	Extend database schemas	.ts	Advanced

1. CREATE_FILE Action

Purpose: Create new files with content or templates.

interface CreateFileAction {
  type: 'CREATE_FILE';
  path: string;                    // Required: File path
  content?: string;                // File content (or use template)
  template?: string;               // Template file path
  overwrite?: boolean;             // Overwrite existing files
  conflictResolution?: ConflictResolution;
  mergeInstructions?: MergeInstructions;
}

Examples:

// Create a simple file
{
  type: 'CREATE_FILE',
  path: 'src/components/Button.tsx',
  content: 'export function Button() { return <button>Click me</button>; }'
}
 
// Create from template
{
  type: 'CREATE_FILE',
  path: 'src/pages/login.tsx',
  template: 'templates/login-page.tsx.tpl'
}
 
// Create with conflict resolution
{
  type: 'CREATE_FILE',
  path: 'src/lib/auth.ts',
  content: 'export const auth = {};',
  conflictResolution: {
    strategy: 'merge',
    instructions: { /* ... */ }
  }
}

2. ENHANCE_FILE Action

Purpose: Modify existing files using modifiers.

interface EnhanceFileAction {
  type: 'ENHANCE_FILE';
  path: string;                    // Required: File path
  modifier: ModifierType;          // Required: Modifier type
  params?: Record<string, any>;    // Modifier parameters
  fallback?: EnhanceFileFallbackStrategy;
}

Examples:

// Add dependencies to package.json
{
  type: 'ENHANCE_FILE',
  path: 'package.json',
  modifier: 'package-json-merger',
  params: {
    dependencies: {
      'react': '^18.0.0',
      'next': '^14.0.0'
    }
  }
}
 
// Wrap JSX children with providers
{
  type: 'ENHANCE_FILE',
  path: 'src/app/layout.tsx',
  modifier: 'jsx-children-wrapper',
  params: {
    providers: [{
      component: 'QueryProvider',
      import: { name: 'QueryProvider', from: '@/lib/query' },
      props: { enableDevtools: true }
    }]
  }
}

3. INSTALL_PACKAGES Action

Purpose: Install npm packages.

interface InstallPackagesAction {
  type: 'INSTALL_PACKAGES';
  packages: string[];              // Required: Package names
  isDev?: boolean;                // Dev dependencies
}

Examples:

// Install production packages
{
  type: 'INSTALL_PACKAGES',
  packages: ['react', 'next', 'typescript']
}
 
// Install dev packages
{
  type: 'INSTALL_PACKAGES',
  packages: ['@types/react', 'eslint'],
  isDev: true
}

4. ADD_SCRIPT Action

Purpose: Add npm scripts to package.json.

interface AddScriptAction {
  type: 'ADD_SCRIPT';
  name: string;                    // Required: Script name
  command: string;                 // Required: Script command
}

Examples:

// Add build script
{
  type: 'ADD_SCRIPT',
  name: 'build',
  command: 'next build'
}
 
// Add dev script
{
  type: 'ADD_SCRIPT',
  name: 'dev',
  command: 'next dev'
}

5. ADD_ENV_VAR Action

Purpose: Add environment variables.

interface AddEnvVarAction {
  type: 'ADD_ENV_VAR';
  key: string;                     // Required: Variable key
  value: string;                   // Required: Variable value
  path?: string;                   // Environment file path
  description?: string;            // Optional description
}

Examples:

// Add database URL
{
  type: 'ADD_ENV_VAR',
  key: 'DATABASE_URL',
  value: 'postgresql://localhost:5432/myapp',
  description: 'PostgreSQL database connection string'
}
 
// Add API key
{
  type: 'ADD_ENV_VAR',
  key: 'NEXT_PUBLIC_API_URL',
  value: 'https://api.myapp.com'
}

6-15. Other Actions

For brevity, here are the remaining actions with their key parameters:

APPEND_TO_FILE:

{
  type: 'APPEND_TO_FILE',
  path: string,
  content: string
}

PREPEND_TO_FILE:

{
  type: 'PREPEND_TO_FILE',
  path: string,
  content: string
}

RUN_COMMAND:

{
  type: 'RUN_COMMAND',
  command: string,
  workingDir?: string
}

MERGE_JSON:

{
  type: 'MERGE_JSON',
  path: string,
  content: Record<string, any>
}

ADD_TS_IMPORT:

{
  type: 'ADD_TS_IMPORT',
  path: string,
  imports: ImportDefinition[]
}

ADD_DEPENDENCY:

{
  type: 'ADD_DEPENDENCY',
  packages: string[],
  isDev?: boolean
}

ADD_DEV_DEPENDENCY:

{
  type: 'ADD_DEV_DEPENDENCY',
  packages: string[]
}

MERGE_CONFIG:

{
  type: 'MERGE_CONFIG',
  path: string,
  strategy: 'deep-merge' | 'shallow-merge' | 'replace',
  config: Record<string, any>
}

WRAP_CONFIG:

{
  type: 'WRAP_CONFIG',
  path: string,
  wrapper: string,
  options?: Record<string, any>
}

EXTEND_SCHEMA:

{
  type: 'EXTEND_SCHEMA',
  path: string,
  tables: SchemaTable[],
  additionalImports?: string[]
}

🔧 MODIFIERS REFERENCE

Modifier Types Overview

The Architech supports 13 modifier types for file enhancement.

Modifier Type	Purpose	File Types	Method
`package-json-merger`	Merge package.json	.json	JSON
`tsconfig-enhancer`	Enhance tsconfig.json	.json	JSON
`css-enhancer`	Append CSS styles	.css	Text
`js-config-merger`	Merge JS configs	.js, .ts	AST
`ts-module-enhancer`	Enhance TS modules	.ts, .tsx	AST
`json-merger`	Generic JSON merge	.json	JSON
`js-export-wrapper`	Wrap JS exports	.js, .ts	AST
`jsx-children-wrapper`	Wrap JSX children	.tsx, .jsx	AST
`yaml-merger`	Merge YAML files	.yml, .yaml	YAML
`env-merger`	Merge .env files	.env	Text
`dockerfile-merger`	Merge Dockerfiles	Dockerfile	Text
`dockerignore-merger`	Merge .dockerignore	.dockerignore	Text

1. package-json-merger

Purpose: Merge dependencies, scripts, and properties into package.json.

interface PackageJsonMergerParams {
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  scripts?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  optionalDependencies?: Record<string, string>;
  engines?: Record<string, string>;
  browserslist?: string[];
}

Examples:

// Add dependencies and scripts
{
  modifier: 'package-json-merger',
  params: {
    dependencies: {
      'react': '^18.0.0',
      'next': '^14.0.0'
    },
    scripts: {
      'dev': 'next dev',
      'build': 'next build'
    }
  }
}

2. tsconfig-enhancer

Purpose: Enhance tsconfig.json with compiler options and paths.

interface TsconfigEnhancerParams {
  compilerOptions?: Record<string, any>;
  paths?: Record<string, string[]>;
  include?: string[];
  exclude?: string[];
  extends?: string;
  mergeStrategy?: 'merge' | 'replace';
}

Examples:

// Add compiler options and paths
{
  modifier: 'tsconfig-enhancer',
  params: {
    compilerOptions: {
      strict: true,
      noImplicitAny: true
    },
    paths: {
      '@/*': ['./src/*'],
      '@/components/*': ['./src/components/*']
    }
  }
}

3. jsx-children-wrapper

Purpose: Wrap {children} in JSX with provider components.

interface JsxChildrenWrapperParams {
  providers: Array<{
    component: string;
    import: {
      name: string;
      from: string;
      isDefault?: boolean;
    };
    props?: Record<string, string | boolean | number>;
  }>;
  targetElement?: string;
}

Examples:

// Wrap with providers
{
  modifier: 'jsx-children-wrapper',
  params: {
    providers: [
      {
        component: 'QueryProvider',
        import: { name: 'QueryProvider', from: '@/lib/query' },
        props: { enableDevtools: true }
      },
      {
        component: 'ThemeProvider',
        import: { name: 'ThemeProvider', from: '@/lib/theme' }
      }
    ],
    targetElement: 'body'
  }
}

4-13. Other Modifiers

For brevity, here are the remaining modifiers with their key parameters:

css-enhancer:

{
  modifier: 'css-enhancer',
  params: {
    styles: string
  }
}

js-config-merger:

{
  modifier: 'js-config-merger',
  params: {
    targetProperties: Record<string, any>,
    mergeStrategy: 'merge' | 'replace' | 'append'
  }
}

ts-module-enhancer:

{
  modifier: 'ts-module-enhancer',
  params: {
    importsToAdd: Array<{
      name: string;
      from: string;
      type?: 'import' | 'type';
      isDefault?: boolean;
    }>;
    statementsToAppend: Array<{
      type: 'raw' | 'function' | 'const' | 'interface' | 'type';
      content: string;
    }>;
  }
}

json-merger:

{
  modifier: 'json-merger',
  params: {
    merge: Record<string, any>;
    strategy: 'deep' | 'shallow';
  }
}

js-export-wrapper:

{
  modifier: 'js-export-wrapper',
  params: {
    wrapperFunction: string;
    wrapperImport: {
      name: string;
      from: string;
      isDefault?: boolean;
    };
    wrapperOptions?: Record<string, any>;
  }
}

yaml-merger:

{
  modifier: 'yaml-merger',
  params: {
    merge: Record<string, any>;
    strategy: 'deep' | 'shallow';
  }
}

env-merger:

{
  modifier: 'env-merger',
  params: {
    variables: Record<string, string>;
    comments?: Record<string, string>;
  }
}

dockerfile-merger:

{
  modifier: 'dockerfile-merger',
  params: {
    content: string;
    strategy: 'append' | 'prepend' | 'replace';
  }
}

dockerignore-merger:

{
  modifier: 'dockerignore-merger',
  params: {
    patterns: string[];
    strategy: 'append' | 'prepend' | 'replace';
  }
}

🛣️ PATH VARIABLES

Available Path Variables

The Architech provides 25+ path variables for framework-agnostic file paths.

Variable	Purpose	Example
`{{paths.source_root}}`	Source code root	`src/`
`{{paths.app_root}}`	App directory	`src/app/`
`{{paths.pages_root}}`	Pages directory	`src/pages/`
`{{paths.components}}`	Components directory	`src/components/`
`{{paths.ui_components}}`	UI components	`src/components/ui/`
`{{paths.lib}}`	Library code	`src/lib/`
`{{paths.hooks}}`	React hooks	`src/hooks/`
`{{paths.stores}}`	State stores	`src/stores/`
`{{paths.api_routes}}`	API routes	`src/app/api/`
`{{paths.middleware}}`	Middleware	`src/middleware.ts`
`{{paths.config}}`	Configuration	`src/config/`
`{{paths.types}}`	Type definitions	`src/types/`
`{{paths.styles}}`	Stylesheets	`src/styles/`
`{{paths.assets}}`	Static assets	`public/`
`{{paths.tests}}`	Test files	`src/__tests__/`

Feature-Specific Paths

Variable	Purpose	Example
`{{paths.database_config}}`	Database config	`src/lib/db/`
`{{paths.auth_config}}`	Auth config	`src/lib/auth/`
`{{paths.payment_config}}`	Payment config	`src/lib/payments/`
`{{paths.email_config}}`	Email config	`src/lib/email/`
`{{paths.observability_config}}`	Monitoring config	`src/lib/monitoring/`
`{{paths.state_config}}`	State config	`src/lib/state/`
`{{paths.testing_config}}`	Testing config	`src/lib/testing/`
`{{paths.deployment_config}}`	Deployment config	`deploy/`
`{{paths.content_config}}`	Content config	`src/lib/content/`
`{{paths.blockchain_config}}`	Blockchain config	`src/lib/blockchain/`

Usage Examples

// Create component
{
  type: 'CREATE_FILE',
  path: '{{paths.components}}/Button.tsx',
  content: 'export function Button() { return <button>Click me</button>; }'
}
 
// Create API route
{
  type: 'CREATE_FILE',
  path: '{{paths.api_routes}}/users/route.ts',
  content: 'export async function GET() { return Response.json({ users: [] }); }'
}
 
// Create hook
{
  type: 'CREATE_FILE',
  path: '{{paths.hooks}}/useAuth.ts',
  content: 'export function useAuth() { /* ... */ }'
}

🎯 TEMPLATE CONTEXT

Available Context Variables

The Architech provides rich context for template rendering.

interface ProjectContext {
  // Project metadata
  name: string;
  description: string;
  version: string;
  
  // Paths
  paths: Record<string, string>;
  
  // Environment
  env: Record<string, string>;
  
  // Module parameters
  moduleParams: Record<string, any>;
  
  // Feature flags
  features: Record<string, boolean>;
  
  // Dependencies
  dependencies: string[];
  devDependencies: string[];
}

Usage in Templates

// Template file: templates/component.tsx.tpl
export function {{componentName}}() {
  return (
    <div className="{{className}}">
      <h1>{{title}}</h1>
      <p>{{description}}</p>
    </div>
  );
}

Conditional Rendering

// Conditional content
{
  type: 'CREATE_FILE',
  path: '{{paths.components}}/Button.tsx',
  content: `
    export function Button() {
      return (
        <button>
          {{#if hasIcon}}
            <Icon name="{{iconName}}" />
          {{/if}}
          {{text}}
        </button>
      );
    }
  `,
  condition: 'moduleParams.hasButton === true'
}

🎯 BEST PRACTICES

1. Action Selection

Use CREATE_FILE for:

New files
Simple content
Templates

Use ENHANCE_FILE for:

Modifying existing files
Adding dependencies
Wrapping components

Use INSTALL_PACKAGES for:

Package installation
Dependency management

2. Modifier Selection

Use JSON-based modifiers for:

package.json
tsconfig.json
Configuration files

Use AST-based modifiers for:

TypeScript files
JavaScript files
Complex transformations

Use text-based modifiers for:

CSS files
Environment files
Simple text files

3. Path Variables

Always use path variables:

Framework-agnostic
Consistent across projects
Easy to maintain

Examples:

// ✅ Good
path: '{{paths.components}}/Button.tsx'
 
// ❌ Bad
path: 'src/components/Button.tsx'

4. Error Handling

Use fallback strategies:

{
  type: 'ENHANCE_FILE',
  path: 'package.json',
  modifier: 'package-json-merger',
  fallback: 'CREATE'  // Create if file doesn't exist
}

Use conflict resolution:

{
  type: 'CREATE_FILE',
  path: 'src/index.ts',
  content: 'export * from "./lib";',
  conflictResolution: {
    strategy: 'merge',
    instructions: { /* ... */ }
  }
}

5. Conditional Execution

Use conditions for optional features:

{
  type: 'CREATE_FILE',
  path: '{{paths.components}}/AuthButton.tsx',
  content: '/* Auth button component */',
  condition: 'moduleParams.hasAuth === true'
}

Use forEach for arrays:

{
  type: 'CREATE_FILE',
  path: '{{paths.components}}/{{item.name}}.tsx',
  content: '/* {{item.name}} component */',
  forEach: 'moduleParams.components'
}

📝 REAL EXAMPLES

Example 1: Simple Adapter Blueprint

export const blueprint: Blueprint = {
  id: 'ui/button',
  name: 'Button Component',
  actions: [
    // Install dependencies
    {
      type: 'INSTALL_PACKAGES',
      packages: ['react', 'typescript']
    },
    
    // Create component
    {
      type: 'CREATE_FILE',
      path: '{{paths.components}}/Button.tsx',
      content: `
        import React from 'react';
        
        interface ButtonProps {
          children: React.ReactNode;
          onClick?: () => void;
          variant?: 'primary' | 'secondary';
        }
        
        export function Button({ children, onClick, variant = 'primary' }: ButtonProps) {
          return (
            <button 
              onClick={onClick}
              className={\`btn btn-\${variant}\`}
            >
              {children}
            </button>
          );
        }
      `
    },
    
    // Add to package.json
    {
      type: 'ENHANCE_FILE',
      path: 'package.json',
      modifier: 'package-json-merger',
      params: {
        scripts: {
          'build:button': 'tsc src/components/Button.tsx'
        }
      }
    }
  ]
};

Example 2: SDK-Backend Connector Blueprint

export const blueprint: Blueprint = {
  id: 'connectors/auth/better-auth-nextjs',
  name: 'Better Auth Next.js Connector',
  actions: [
    // Install packages
    {
      type: 'INSTALL_PACKAGES',
      packages: ['better-auth', '@better-auth/nextjs']
    },
    
    // Create auth config
    {
      type: 'CREATE_FILE',
      path: '{{paths.auth_config}}/better-auth.ts',
      content: `
        import { betterAuth } from 'better-auth';
        import { nextjs } from '@better-auth/nextjs';
        
        export const auth = betterAuth({
          database: {
            // Database config
          },
          plugins: [nextjs()],
          // ... other config
        });
      `
    },
    
    // Create API route
    {
      type: 'CREATE_FILE',
      path: '{{paths.api_routes}}/auth/[...all]/route.ts',
      content: `
        import { auth } from '@/lib/auth/better-auth';
        import { toNextJsHandler } from '@better-auth/nextjs';
        
        const handler = toNextJsHandler(auth);
        export { handler as GET, handler as POST };
      `
    },
    
    // Create client
    {
      type: 'CREATE_FILE',
      path: '{{paths.auth_config}}/client.ts',
      content: `
        import { createAuthClient } from 'better-auth/react';
        
        export const authClient = createAuthClient({
          baseURL: process.env.NEXT_PUBLIC_APP_URL
        });
      `
    },
    
    // Wrap layout with provider
    {
      type: 'ENHANCE_FILE',
      path: '{{paths.app_root}}/layout.tsx',
      modifier: 'jsx-children-wrapper',
      params: {
        providers: [
          {
            component: 'AuthProvider',
            import: { name: 'AuthProvider', from: '@/lib/auth/provider' }
          }
        ]
      }
    },
    
    // Add environment variables
    {
      type: 'ADD_ENV_VAR',
      key: 'BETTER_AUTH_SECRET',
      value: 'your-secret-key',
      description: 'Better Auth secret key'
    }
  ]
};

Example 3: Complex Feature Blueprint

export const blueprint: Blueprint = {
  id: 'features/ai-chat',
  name: 'AI Chat Feature',
  actions: [
    // Install packages
    {
      type: 'INSTALL_PACKAGES',
      packages: ['ai', '@ai-sdk/openai', 'zod']
    },
    
    // Create backend API
    {
      type: 'CREATE_FILE',
      path: '{{paths.api_routes}}/chat/route.ts',
      content: `
        import { openai } from '@ai-sdk/openai';
        import { streamText } from 'ai';
        
        export async function POST(req: Request) {
          const { messages } = await req.json();
          
          const result = await streamText({
            model: openai('gpt-3.5-turbo'),
            messages,
          });
          
          return result.toDataStreamResponse();
        }
      `
    },
    
    // Create tech-stack hook
    {
      type: 'CREATE_FILE',
      path: '{{paths.hooks}}/useAIChat.ts',
      content: `
        import { useChat } from 'ai/react';
        
        export function useAIChat() {
          const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
          
          return {
            messages,
            input,
            handleInputChange,
            handleSubmit,
            isLoading
          };
        }
      `
    },
    
    // Create UI component
    {
      type: 'CREATE_FILE',
      path: '{{paths.components}}/ChatInterface.tsx',
      content: `
        import { useAIChat } from '@/hooks/useAIChat';
        
        export function ChatInterface() {
          const { messages, input, handleInputChange, handleSubmit, isLoading } = useAIChat();
          
          return (
            <div className="chat-container">
              <div className="messages">
                {messages.map((message) => (
                  <div key={message.id} className={\`message \${message.role}\`}>
                    {message.content}
                  </div>
                ))}
              </div>
              <form onSubmit={handleSubmit}>
                <input
                  value={input}
                  onChange={handleInputChange}
                  placeholder="Type your message..."
                  disabled={isLoading}
                />
                <button type="submit" disabled={isLoading}>
                  Send
                </button>
              </form>
            </div>
          );
        }
      `
    },
    
    // Add environment variables
    {
      type: 'ADD_ENV_VAR',
      key: 'OPENAI_API_KEY',
      value: 'your-openai-key',
      description: 'OpenAI API key for AI chat'
    }
  ]
};

🎯 SUMMARY

This guide provides everything an AI agent needs to create blueprints automatically:

15 Blueprint Actions - Complete reference with parameters
13 Modifiers - File enhancement capabilities
25+ Path Variables - Framework-agnostic paths
Template Context - Available variables and conditions
Best Practices - AI-specific guidelines
Real Examples - Working blueprint patterns

Use this reference to create sophisticated, production-ready blueprints that follow Architech best practices.

Creating Your Marketplace Genomes Catalog