🧪 BenchMate - AI-Powered Protocol Builder & Executor

"Dictate, not click. Automate, not babysit."

BenchMate is a modern protocol management system for laboratories. Built with Next.js and Fastify, it enables scientists to create, manage, and execute protocols — with a roadmap toward voice-first and AI-assisted workflows.

🌟 Current Features

• 📋 Protocol Management: Create, list, and view lab protocols with full CRUD API
• 🗄️ Rich Data Model: Protocols with steps, materials, equipment, runs, and device events
• ⚡ Redis Caching: Intelligent caching layer for fast protocol reads
• 📖 Auto-Generated API Docs: Interactive Swagger UI at /documentation
• 🔌 MCP Server Ready: Model Context Protocol SDK integrated for future AI tooling

🔭 Vision

BenchMate is being built toward a voice-first, AI-assisted lab experience:

• 🎤 Voice-First Protocol Creation: Speak your protocol naturally and let AI structure it
• 🤖 AI Protocol Parser: Import protocols from papers, PDFs, or natural language
• ⚡ Automated Execution: Device telemetry automatically checks off completed steps
• 📊 Real-time Dashboard: Monitor protocol execution with live device status
• 🔌 Device Integration: Connect lab equipment via webhooks, MQTT, or vendor APIs
• 📱 Offline Support: Execute protocols even without internet connection (PWA)

🏗️ Architecture

graph TB
    Browser["🌐 Browser"] --> Frontend

    subgraph Frontend["Next.js Frontend (Port 3000)"]
        Pages["Pages & Server Components"]
        TanStack["TanStack Query"]
    end

    Frontend --> API

    subgraph API["Fastify API (Port 3001)"]
        REST["REST API + Swagger UI"]
        Cache["Redis Cache Layer"]
        ORM["Prisma ORM"]
    end

    API --> DB["🐘 PostgreSQL 16\n(Protocols, Steps, Users)"]
    API --> Redis["⚡ Redis 7\n(Caching)"]

Loading

📦 Monorepo Structure

/benchmate
├── apps/
│   ├── web/                 # Next.js frontend (App Router)
│   └── api/                 # Fastify API service
├── packages/
│   └── shared/              # Shared TypeScript types
├── docker-compose.yml       # Local development services
├── turbo.json               # Turborepo configuration
└── pnpm-workspace.yaml      # pnpm workspace configuration

🚀 Quick Start

Prerequisites

• Node.js 20+
• pnpm 8+ (install: npm install -g pnpm)
• Docker & Docker Compose (for PostgreSQL and Redis)

Installation

1. Clone the repository

   git clone https://github.com/horner/benchmate.git
   cd benchmate

2. Install dependencies

   pnpm install

3. Start infrastructure services

   docker compose up -d

4. Set up environment variables

   cp apps/web/.env.example apps/web/.env.local
   cp apps/api/.env.example apps/api/.env

5. Start development servers

   pnpm dev

Access Points

• Frontend: http://localhost:3000
• API: http://localhost:3001
• API Documentation: http://localhost:3001/documentation
• PostgreSQL: localhost:5432 (user: benchmate, password: benchmate_dev_password)
• Redis: localhost:6379

🛠️ Development Commands

# Start all apps in development mode
pnpm dev

# Start only frontend
pnpm --filter @benchmate/web dev

# Start only API
pnpm --filter @benchmate/api dev

# Build all apps
pnpm build

# Run linters
pnpm lint

# Format code
pnpm format

# Database commands (from apps/api)
cd apps/api
pnpm db:push          # Push schema to database
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Prisma Studio

📚 Technology Stack

Frontend (Next.js)

• Next.js 16 - React framework with App Router
• React 19 - UI library
• TypeScript - Type safety
• Tailwind CSS - Utility-first styling
• TanStack Query - Server state and data fetching

API (Fastify)

• Fastify 5+ - High-performance API framework
• @fastify/swagger - Auto-generated OpenAPI documentation
• TypeBox - Schema validation with automatic type generation
• Prisma 6 - Type-safe database ORM
• ioredis - Redis client for caching
• @modelcontextprotocol/sdk - MCP server for AI integration

Infrastructure

• PostgreSQL 16 - Primary database
• Redis 7 - Caching layer
• Docker Compose - Local development environment

📖 Documentation

• API Documentation - Interactive Swagger UI
• Architecture Decision Records - Coming soon
• Contributing Guidelines - Coming soon

🗺️ Roadmap

✅ Phase 1: Foundation

• Monorepo setup with Turborepo
• Next.js frontend scaffolding
• Fastify API with Swagger
• Docker Compose for local development

✅ Phase 2: Database & API Foundation

• Full database schema with Prisma (12 models)
• Protocol CRUD REST API
• Redis caching layer
• TypeBox schema validation
• Seed script for sample data

✅ Phase 3: Protocol Listing UI

• Protocol list page
• Protocol detail page
• New protocol form
• TanStack Query integration

🚧 Phase 4: Voice & AI (Planned)

• Voice input integration
• AI protocol parser
• Protocol import from text/PDF
• Smart suggestions and auto-complete

📅 Phase 5: Execution Engine (Planned)

• Protocol run tracking
• Real-time execution dashboard
• Timer and manual completion modes
• Voice command execution control

🔮 Phase 6: Device Integration (Planned)

• Webhook receiver for device events
• Device registration and mapping
• Auto-completion triggers
• Real-time event visualization

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.

📄 License

MIT License

🙏 Acknowledgments

• Inspired by SciNote for protocol management
• Built with Model Context Protocol (MCP) for AI integration
• Powered by Next.js and Fastify

---

Built with ❤️ for scientists who deserve better tools