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
  • Trade on the marketplace - Buy and sell rare beers with integrated Stripe payments
  • Rate and review - Comprehensive tasting notes with flavor profiles
  • Connect with collectors - Follow other users, share activity, and discover new beers
  • 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
TailwindCSSUtility-first styling
shadcn-svelteAccessible component library
Paraglide.jsType-safe internationalization
StripePayment processing
PWAOffline support and installability

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

Marketplace Flow

The peer-to-peer marketplace enables secure trading:

Text
Seller lists beer → Buyer initiates purchase → 
Stripe payment intent → Seller confirms shipment → 
Buyer confirms receipt → Funds released

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

Social Features

Technical Reference

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.