BrewHoard Documentation

Complete guide to building, deploying, and extending the BrewHoard beer collection management application.

Welcome to the BrewHoard documentation. BrewHoard is a comprehensive beer collection management application built with modern web technologies. This documentation covers everything from initial setup to advanced customization.

What is BrewHoard?

BrewHoard is a full-featured Progressive Web Application (PWA) designed for beer enthusiasts to:

  • Manage their beer collection - Track bottles, cans, and kegs with detailed metadata
  • Scan and identify beers - AI-powered image recognition for instant beer identification
  • Rate and review - Comprehensive tasting notes with flavor profiles
  • Track consumption history - Monitor what you’ve enjoyed and when
  • Export data - Generate reports in multiple formats (JSON, CSV, PDF)

Technology Stack

BrewHoard is built on a modern, performant stack:

TechnologyPurpose
SvelteKitFull-stack framework with SSR and API routes
Svelte 5Reactive UI with runes ($state, $derived, $effect)
PostgreSQLRelational database via porsager/postgres and postgres-shift migrations
Drizzle ORMType-safe query builder and schema definitions
Better AuthAuthentication with session management and OAuth
TailwindCSSUtility-first styling
shadcn-svelteAccessible component library (built on bits-ui)
Paraglide.jsType-safe internationalization
StripePayment processing
Socket.IOReal-time updates
MinIOS3-compatible object storage for photos
PWAOffline support and installability via vite-plugin-pwa

Quick Links

Get started quickly with these essential guides:

Core Concepts

Collection Management

The heart of BrewHoard is the collection system. Each user has a personal collection where they can:

JavaScript
// Adding a beer to collection via API
const response = await fetch('/api/v1/collection', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    beer_id: 'uuid-of-beer',
    quantity: 6,
    purchase_price: 12.99,
    purchase_location: 'Local Brewery',
    storage_location: 'Beer Fridge',
    notes: 'Anniversary edition'
  })
});

The Scanner System

BrewHoard includes an AI-powered scanner that can identify beers from photos:

  1. User captures or uploads a photo
  2. Image is processed client-side for optimization
  3. Vision AI analyzes labels, logos, and text
  4. Matching beers are suggested from the database
  5. User confirms or manually selects the correct beer

Project Philosophy

BrewHoard follows these core principles:

  1. Type Safety - JSDoc annotations provide TypeScript-like safety without a build step
  2. Progressive Enhancement - Works without JavaScript, enhanced with it
  3. Accessibility First - WCAG 2.1 AA compliance throughout
  4. Offline Capable - Service worker caches essential resources
  5. Mobile First - Responsive design optimized for handheld devices

Documentation Structure

This documentation is organized into logical sections:

Getting Started

Core Features

Technical Reference

MCP & Integrations

Deployment

Contributing

BrewHoard is open source. Contributions are welcome! See our GitHub repository for:

  • Issue tracking
  • Pull request guidelines
  • Development setup
  • Code of conduct

Ready to get started? Head to the Installation Guide to set up your development environment.