Wellpipe Developer Documentation

Welcome to the Wellpipe developer documentation. This guide covers building integrations, contributing to Wellpipe, and understanding the architecture.

What is Wellpipe?

Wellpipe is a health data API aggregator that connects wearable platforms (WHOOP, Oura, Fitbit) to AI assistants via MCP (Model Context Protocol). It provides:

• Unified API - Consistent interface across health providers
• MCP Tools - Ready-to-use tools for AI assistants
• OAuth Management - Secure token handling and refresh
• Cloud + Self-Hosted - Flexible deployment options

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistants                          │
│              (Claude, ChatGPT, Custom)                      │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP / REST API
┌──────────────────────────▼──────────────────────────────────┐
│                      Wellpipe                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  @wellpipe  │  │  @wellpipe  │  │  @wellpipe  │         │
│  │    /core    │  │   /whoop    │  │    /cli     │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
                           │ OAuth / API
┌──────────────────────────▼──────────────────────────────────┐
│                   Health Providers                           │
│              (WHOOP, Oura, Fitbit, etc.)                    │
└─────────────────────────────────────────────────────────────┘

Packages

Package	Description	Visibility
@wellpipe/core	Shared interfaces, types, utilities	Public
@wellpipe/whoop	WHOOP API integration	Public
@wellpipe/cli	CLI for self-hosting	Public
wellpipe-cloud	SaaS backend	Private

Quick Links

Getting Started

• Local Development Setup
• Running Tests

Building Integrations

• Building a Provider
• Adding MCP Tools

Contributing

• Code Style Guide
• Pull Request Guidelines

Reference

• API Reference
• Architecture Details

Design Principles

1. Minimal Dependencies

• @wellpipe/core only depends on zod
• Providers only depend on @wellpipe/core
• Keeps bundles small and auditable

2. Type Safety

• Strict TypeScript throughout
• Runtime validation with Zod
• Explicit return types on public APIs

3. Provider Independence

• Each provider is a separate package
• Providers handle API specifics
• Core handles common patterns

4. OAuth Separation

• Providers don't handle OAuth flows
• CLI and Cloud handle token management
• Providers receive ready-to-use tokens

Repository Structure

wellpipe/
├── core/              # @wellpipe/core
│   └── src/
│       ├── interfaces/
│       └── types/
├── provider-whoop/    # @wellpipe/whoop
│   └── src/
│       ├── client/
│       └── tools/
├── cli/               # @wellpipe/cli
│   └── src/
│       ├── auth/
│       └── mcp/
├── cloud/             # wellpipe-cloud (private)
│   └── src/
│       └── app/
└── docs/              # This documentation

Technology Stack

Layer	Technology
Language	TypeScript (strict mode)
Runtime	Node.js 18+
Validation	Zod
Testing	Vitest
MCP Protocol	@modelcontextprotocol/sdk
Cloud Backend	Next.js + Prisma