Core Concepts

MCP (Model Context Protocol)

The Model Context Protocol (MCP) is a standardized protocol that allows AI assistants like Claude to interact with external tools and data. BigRack implements this protocol to provide persistent, structured context to AI development tools.

Via MCP, Claude can query BigRack to get business context, plan tasks, and validate that code respects defined rules.

Repos and Projects

Hierarchical architecture

BigRack Installation
│
├── Repo: "E-commerce Platform"
│   │
│   ├── 📚 Business Context (shared)
│   │   ├── Business Rules
│   │   ├── Glossary Entries
│   │   ├── Architecture Patterns
│   │   └── Team Conventions
│   │
│   └── 📋 Projects
│       ├── Project: "Payment Integration"
│       │   ├── Task: "Setup payment gateway API keys"
│       │   ├── Task: "Implement payment processing endpoint"
│       │   ├── Task: "Add payment validation logic"
│       │   └── Task: "Write payment integration tests"
│       ├── Project: "Fix Cart Bug"
│       │   ├── Task: "Reproduce the cart bug"
│       │   ├── Task: "Identify root cause"
│       │   ├── Task: "Implement fix"
│       │   └── Task: "Add regression tests"
│       └── Project: "Add Tests"
│           ├── Task: "Setup test framework"
│           ├── Task: "Add unit tests for core modules"
│           └── Task: "Add integration tests"
│
└── Repo: "Marketing Website"
    └── ...

Repo

A Repo represents a business domain or codebase. It's the main container for your business context.

  • Contains context shared by all projects
  • Can be linked to a Git repository
  • Stores business rules, patterns, and conventions
  • One repo per project directory (bigrack.json file)

Project

A Project represents a specific work unit(feature, bugfix, refactor, etc.).

  • Automatically inherits context from the parent Repo
  • Can have its own specific context
  • Linked to a Git branch
  • Contains tickets with dependencies

Ticket

A Ticket represents an atomic task within a project. It's the smallest unit of work that can be planned, tracked, and completed independently.

  • Belongs to a specific Project
  • Can have dependencies on other tickets (forming a DAG)
  • Has a status (pending, in-progress, completed, blocked)
  • Can include validation criteria and objectives
  • Can be linked to a Git branch for tracking
  • Has a type: setup, implementation, testing, or documentation

Persistent Business Context

Business context is the structured knowledge that allows BigRack to understand your domain and validate that your code respects your rules.

Business Rules

Business rules that must be respected by the code.

Example: "Stock cannot be negative", "Discounts max 70%"

Glossary Entries

Definitions of terms specific to your domain.

Example: "SKU: Stock Keeping Unit", "Cart: Shopping basket"

Architecture Patterns

Patterns and architectural decisions to follow.

Example: "Use Repository pattern", "NestJS for backend"

Team Conventions

Code conventions and team standards.

Example: "Test coverage > 80%", "Use Prettier"

Planning and Decomposition

BigRack can decompose a complex feature into atomic tickets with their dependencies. This creates a dependency graph (DAG) that guides development.

Each ticket can have validation criteria, objectives, and be linked to a Git branch.

Ticket Properties

  • Title: Clear description of the task
  • Status: pending, in-progress, completed, blocked
  • Priority: critical, high, medium, low
  • Dependencies: Other tickets that must be completed first
  • Type: setup, implementation, testing, documentation
  • Validation Criteria: How to verify the task is complete

Vector Search & RAG

BigRack uses vector embeddings and semantic search to find relevant context for your queries. This enables a RAG (Retrieval-Augmented Generation) workflow.

  • All business context is automatically embedded using local ML models
  • Natural language queries return the most relevant context
  • AI assistants can query context automatically during conversations
  • No external API calls - everything runs locally