Architecture Overview | Bootspring Docs

Understanding how Bootspring works under the hood.

System Architecture#

Bootspring is a multi-component system that provides AI-assisted development tools:

┌─────────────────────────────────────────────────────────────────────┐
│                          CLIENT LAYER                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    │
│   │   CLI    │    │  Claude  │    │ VS Code  │    │Dashboard │    │
│   │          │    │ Desktop  │    │Extension │    │   (Web)  │    │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘    │
│        │               │               │               │          │
└────────┼───────────────┼───────────────┼───────────────┼──────────┘
         │               │               │               │
         │               │ MCP Protocol  │               │
         ▼               ▼               ▼               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          MCP SERVER                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────────────────────────────────────────────────────┐     │
│   │                    Tool Registry                          │     │
│   │  assist | context | agent | skill | workflow | ...        │     │
│   └──────────────────────────────────────────────────────────┘     │
│                              │                                      │
│   ┌──────────────────────────┼──────────────────────────────┐      │
│   │                          ▼                               │      │
│   │   ┌────────────┐  ┌────────────┐  ┌────────────┐        │      │
│   │   │   Agent    │  │   Skill    │  │  Workflow  │        │      │
│   │   │   Engine   │  │   Engine   │  │   Engine   │        │      │
│   │   └────────────┘  └────────────┘  └────────────┘        │      │
│   │                    Core Engines                          │      │
│   └──────────────────────────────────────────────────────────┘     │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
         │                                               │
         │ Local                                         │ Remote
         ▼                                               ▼
┌─────────────────────────┐              ┌─────────────────────────┐
│     Local Storage       │              │    Bootspring API       │
├─────────────────────────┤              ├─────────────────────────┤
│                         │              │                         │
│  .bootspring/           │              │  Authentication         │
│    context/             │              │  Usage Tracking         │
│    agents/              │              │  License Validation     │
│    skills/              │              │  Cloud Sync             │
│    config.json          │              │                         │
│                         │              │                         │
└─────────────────────────┘              └─────────────────────────┘

Core Components#

Client Layer#

End-user interfaces:

Component	Description
CLI	Command-line tool for direct interaction
Claude Desktop	MCP integration for Claude
VS Code Extension	IDE integration
Dashboard	Web-based management

MCP Server#

The Model Context Protocol server:

Exposes tools to AI assistants
Manages local state
Orchestrates workflows
Communicates with APIs

Core Engines#

Business logic components:

Engine	Purpose
Agent Engine	Manages expert agent invocations
Skill Engine	Handles pattern application
Workflow Engine	Orchestrates multi-phase processes
Context Engine	Generates and manages context
Quality Engine	Runs quality gates

Data Flow#

Agent Invocation Flow#

User → CLI/MCP → Agent Engine → Context Assembly → LLM → Response → User

User requests agent invocation
CLI/MCP receives request
Agent engine loads agent profile
Context engine assembles relevant context
Request sent to LLM
Response processed and returned

Context Generation Flow#

Codebase → Analyzers → Aggregator → Template → CLAUDE.md

File system scanned
Multiple analyzers extract information
Results aggregated
Template applied
Context file generated

Workflow Orchestration#

Workflow Definition → Phase Manager → Agent Coordination → Completion Signals

Workflow loaded from definition
Phase manager tracks progress
Agents invoked for each phase
Completion signals validate progress

Architecture Docs#

Document	Description
Bootspring Internals	Core system design
MCP Protocol	MCP implementation details
Context System	Context generation
Agent System	Agent architecture
Workflow Engine	Workflow orchestration
Plugin System	Extension architecture

Design Principles#

1. Local-First#

Bootspring operates primarily locally:

No data leaves your machine without consent
Works offline for most features
API calls only for auth/tracking

2. Protocol-Based#

Uses standard protocols:

MCP for AI integration
REST for API
JSON for configuration
Git for version control

3. Extensible#

Built for extension:

Plugin architecture
Custom agents
Custom skills
Custom workflows

4. Non-Invasive#

Doesn't modify your code unless asked:

Generates context files
Suggests changes via AI
Never auto-commits

Technology Stack#

CLI & MCP Server#

Technology	Purpose
Node.js	Runtime
TypeScript	Language
Commander.js	CLI framework
MCP SDK	Protocol implementation

API & Dashboard#

Technology	Purpose
Next.js	Web framework
PostgreSQL	Database
Prisma	ORM
Clerk	Authentication
Stripe	Payments
Vercel	Hosting

AI Integration#

Technology	Purpose
Claude 3.5	Primary AI model
OpenAI (optional)	Alternative provider
LangChain (internal)	LLM orchestration

Deployment Architecture#

Local Installation#

User Machine
├── bootspring (CLI)
├── .bootspring/
│   ├── config.json
│   ├── context/
│   └── cache/
└── Your Project
    ├── CLAUDE.md
    └── bootspring.config.js

Cloud Services#

                    ┌─────────────────┐
                    │    Vercel CDN   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Dashboard │  │   API    │  │  Webhooks │
        │  (Next.js)│  │ (Next.js)│  │ Handlers  │
        └─────┬─────┘  └─────┬────┘  └─────┬────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │PostgreSQL│  │   Redis  │  │   S3     │
        │  (Neon)  │  │(Upstash) │  │(Backups) │
        └──────────┘  └──────────┘  └──────────┘

Security Architecture#

Authentication Flow#

User → Clerk → JWT → API → Resource

API Key Security#

Keys hashed with bcrypt
Scoped permissions
Audit logging
Rate limiting

Data Protection#

TLS in transit
Encrypted at rest
No code stored server-side
GDPR compliant