Bootspring Internals | Bootspring Docs

Deep dive into the core Bootspring system architecture.

Package Structure#

Bootspring is organized as a monorepo:

bootspring/
├── packages/
│   ├── cli/              # Command-line interface
│   ├── core/             # Core business logic
│   ├── mcp-server/       # MCP server implementation
│   ├── sdk/              # JavaScript/TypeScript SDK
│   └── shared/           # Shared utilities
├── skills/               # Built-in skill patterns
├── agents/               # Agent definitions
├── workflows/            # Workflow definitions
└── templates/            # Project templates

Core Package#

The core package contains the primary business logic:

packages/core/
├── src/
│   ├── agents/           # Agent system
│   │   ├── registry.ts
│   │   ├── invoker.ts
│   │   └── profiles/
│   ├── skills/           # Skill system
│   │   ├── loader.ts
│   │   ├── applier.ts
│   │   └── registry.ts
│   ├── context/          # Context generation
│   │   ├── generator.ts
│   │   ├── analyzers/
│   │   └── templates/
│   ├── workflows/        # Workflow engine
│   │   ├── orchestrator.ts
│   │   ├── phases.ts
│   │   └── signals.ts
│   ├── quality/          # Quality gates
│   │   ├── gates.ts
│   │   └── checks/
│   └── config/           # Configuration
│       ├── loader.ts
│       └── schema.ts
└── tests/

Context Generation System#

Generator Architecture#

// core/context/generator.ts

export class ContextGenerator {
  private analyzers: Analyzer[];
  private template: Template;

  async generate(projectPath: string): Promise<string> {
    // 1. Collect project information
    const projectInfo = await this.collectInfo(projectPath);

    // 2. Run analyzers
    const analyses = await Promise.all(
      this.analyzers.map(a => a.analyze(projectPath))
    );

    // 3. Aggregate results
    const aggregated = this.aggregate(analyses);

    // 4. Apply template
    const context = this.template.render({
      ...projectInfo,
      ...aggregated,
    });

    return context;
  }
}

Built-in Analyzers#

Analyzer	Purpose
`PackageAnalyzer`	package.json analysis
`FrameworkAnalyzer`	Framework detection
`StructureAnalyzer`	Project structure
`DependencyAnalyzer`	Dependency analysis
`DatabaseAnalyzer`	Database schema
`ApiAnalyzer`	API routes
`ComponentAnalyzer`	UI components
`TestAnalyzer`	Test coverage

Analysis Pipeline#

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  File Scan  │───▶│  Analyze    │───▶│  Aggregate  │
└─────────────┘    └─────────────┘    └─────────────┘
                          │
         ┌────────────────┼────────────────┐
         ▼                ▼                ▼
   ┌──────────┐    ┌──────────┐    ┌──────────┐
   │ Package  │    │Framework │    │Structure │
   │ Analyzer │    │ Analyzer │    │ Analyzer │
   └──────────┘    └──────────┘    └──────────┘

Agent System#

Agent Registry#

// core/agents/registry.ts

export class AgentRegistry {
  private agents: Map<string, AgentProfile> = new Map();

  register(profile: AgentProfile): void {
    this.agents.set(profile.name, profile);
  }

  get(name: string): AgentProfile | undefined {
    return this.agents.get(name);
  }

  list(filter?: AgentFilter): AgentProfile[] {
    let results = Array.from(this.agents.values());
    if (filter?.category) {
      results = results.filter(a => a.category === filter.category);
    }
    return results;
  }
}

Agent Profile Structure#

interface AgentProfile {
  name: string;
  displayName: string;
  description: string;
  category: AgentCategory;
  tier: Tier;

  systemPrompt: string;
  capabilities: string[];
  collaborates: string[];

  tools?: Tool[];
  examples?: Example[];
  customInstructions?: string;
}

Agent Invocation#

// core/agents/invoker.ts

export class AgentInvoker {
  async invoke(
    agentName: string,
    prompt: string,
    options: InvokeOptions
  ): Promise<AgentResponse> {
    // 1. Load agent profile
    const agent = this.registry.get(agentName);
    if (!agent) throw new AgentNotFoundError(agentName);

    // 2. Check entitlements
    await this.checkEntitlements(agent);

    // 3. Assemble context
    const context = await this.contextBuilder.build({
      agent,
      project: options.projectId,
      files: options.files,
    });

    // 4. Build messages
    const messages = this.buildMessages(agent, prompt, context);

    // 5. Invoke LLM
    const response = await this.llm.complete(messages, {
      model: this.selectModel(agent),
      maxTokens: options.maxTokens,
      temperature: options.temperature,
    });

    // 6. Process response
    return this.processResponse(response, agent);
  }
}

Skill System#

Skill Loader#

// core/skills/loader.ts

export class SkillLoader {
  private skillsPath: string;
  private cache: Map<string, Skill> = new Map();

  async load(skillPath: string): Promise<Skill> {
    // Check cache
    if (this.cache.has(skillPath)) {
      return this.cache.get(skillPath)!;
    }

    // Load from filesystem
    const fullPath = path.join(this.skillsPath, skillPath);
    const content = await fs.readFile(fullPath, 'utf-8');

    // Parse frontmatter and content
    const skill = this.parseSkill(content);

    // Cache and return
    this.cache.set(skillPath, skill);
    return skill;
  }
}

Skill Structure#

interface Skill {
  name: string;
  path: string;
  category: string;
  description: string;
  tier: Tier;

  frontmatter: Record<string, unknown>;
  content: string;
  codeBlocks: CodeBlock[];
  files: SkillFile[];
}

Skill Application#

// core/skills/applier.ts

export class SkillApplier {
  async apply(skill: Skill, options: ApplyOptions): Promise<ApplyResult> {
    const result: ApplyResult = {
      applied: [],
      skipped: [],
      errors: [],
    };

    for (const file of skill.files) {
      try {
        // Process template
        const content = await this.processTemplate(file.content, options.vars);

        // Determine target path
        const targetPath = this.resolveTargetPath(file.path, options.target);

        // Apply file
        if (options.dryRun) {
          result.applied.push({ path: targetPath, action: 'would-create' });
        } else {
          await this.writeFile(targetPath, content);
          result.applied.push({ path: targetPath, action: 'created' });
        }
      } catch (error) {
        result.errors.push({ path: file.path, error });
      }
    }

    return result;
  }
}

Workflow Engine#

Orchestrator#

// core/workflows/orchestrator.ts

export class WorkflowOrchestrator {
  async execute(workflow: Workflow, options: ExecuteOptions): Promise<WorkflowResult> {
    const execution = new WorkflowExecution(workflow);

    for (const phase of workflow.phases) {
      // Check if phase can start
      if (!this.canStartPhase(execution, phase)) {
        await this.handleBlockedPhase(execution, phase);
        continue;
      }

      // Execute phase
      execution.startPhase(phase.name);

      try {
        // Run phase tasks
        const tasks = this.getPhasesTasks(phase);
        const results = phase.parallel
          ? await this.runParallel(tasks, execution)
          : await this.runSequential(tasks, execution);

        // Check completion signals
        const completed = await this.checkCompletionSignals(phase, results);

        if (completed) {
          execution.completePhase(phase.name);
        } else {
          execution.failPhase(phase.name, 'Completion signals not met');
        }
      } catch (error) {
        execution.failPhase(phase.name, error.message);

        if (phase.critical) {
          throw new WorkflowAbortedError(workflow.name, phase.name);
        }
      }
    }

    return execution.getResult();
  }
}

Phase Management#

interface Phase {
  name: string;
  description: string;
  agents: string[];
  tasks: Task[];
  parallel: boolean;
  critical: boolean;
  completionSignals: CompletionSignal[];
  rollbackStrategy?: RollbackStrategy;
}

interface CompletionSignal {
  type: 'file_exists' | 'test_passes' | 'manual' | 'api_response';
  config: Record<string, unknown>;
}

Configuration System#

Config Loader#

// core/config/loader.ts

export class ConfigLoader {
  private configPaths = [
    'bootspring.config.js',
    'bootspring.config.ts',
    'bootspring.config.json',
  ];

  async load(projectPath: string): Promise<Config> {
    // Find config file
    const configPath = await this.findConfig(projectPath);

    if (!configPath) {
      return this.defaultConfig();
    }

    // Load and validate
    const rawConfig = await this.loadFile(configPath);
    const validated = this.validate(rawConfig);

    return validated;
  }
}

Configuration Schema#

interface Config {
  project: {
    name: string;
    type: ProjectType;
  };

  context: {
    path: string;
    include: string[];
    exclude: string[];
    autoRegenerate: boolean;
  };

  agents: {
    enabled: string[];
    customInstructions: Record<string, string>;
  };

  skills: {
    paths: string[];
    customSkills: string;
  };

  quality: {
    preCommit: QualityConfig;
    prePush: QualityConfig;
    preDeploy: QualityConfig;
  };

  mcp: {
    port: number;
    transport: 'stdio' | 'http';
  };
}

Event System#

Event Emitter#

// core/events/emitter.ts

export class BootspringEvents extends EventEmitter {
  emit(event: EventType, payload: EventPayload): boolean {
    // Log event
    this.logger.debug(`Event: ${event}`, payload);

    // Track if enabled
    if (this.trackingEnabled) {
      this.tracker.track(event, payload);
    }

    return super.emit(event, payload);
  }
}

Event Types#

Event	When Fired
`context.generated`	Context file created
`agent.invoked`	Agent called
`agent.completed`	Agent finished
`skill.applied`	Skill applied
`workflow.started`	Workflow begun
`workflow.completed`	Workflow finished
`quality.passed`	Quality gate passed
`quality.failed`	Quality gate failed

Caching#

Cache Manager#

// core/cache/manager.ts

export class CacheManager {
  private memoryCache: Map<string, CacheEntry> = new Map();
  private diskCache: DiskCache;

  async get<T>(key: string): Promise<T | null> {
    // Check memory cache
    const memEntry = this.memoryCache.get(key);
    if (memEntry && !this.isExpired(memEntry)) {
      return memEntry.value as T;
    }

    // Check disk cache
    const diskEntry = await this.diskCache.get(key);
    if (diskEntry && !this.isExpired(diskEntry)) {
      // Populate memory cache
      this.memoryCache.set(key, diskEntry);
      return diskEntry.value as T;
    }

    return null;
  }

  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
    const entry: CacheEntry = {
      value,
      expires: ttl ? Date.now() + ttl : undefined,
    };

    this.memoryCache.set(key, entry);
    await this.diskCache.set(key, entry);
  }
}

Error Handling#

Error Hierarchy#

// Bootspring error base
export class BootspringError extends Error {
  code: string;
  context?: Record<string, unknown>;
}

// Specific errors
export class AgentNotFoundError extends BootspringError {
  code = 'AGENT_NOT_FOUND';
}

export class SkillNotFoundError extends BootspringError {
  code = 'SKILL_NOT_FOUND';
}

export class WorkflowAbortedError extends BootspringError {
  code = 'WORKFLOW_ABORTED';
}

export class EntitlementError extends BootspringError {
  code = 'ENTITLEMENT_REQUIRED';
}