BrewLog Backend API

A privacy-first, offline-first beer tracking application backend

🎯 Project Overview

BrewLog is a private, offline-capable API for tracking beer consumption and preferences. Built with Node.js, TypeScript, and modern security practices.

Key Features

• 🛡️ Privacy-first design with local-first data storage
• 📱 Offline-first architecture with sync capabilities
• 🔒 Zero data collection beyond what's necessary
• 🚀 RESTful API with comprehensive documentation
• 🧪 Comprehensive testing with >80% coverage

Core Principles

• Privacy by Design: No analytics, tracking, or unnecessary data collection
• Local First: Prioritize local storage over cloud
• Data Minimization: Only collect what's absolutely necessary
• Security First: Modern security practices and encryption
• Open Source: Transparent and community-driven

🏗️ Architecture

src/
├── features/              # Feature-based architecture
│   ├── beers/            # Beer management
│   ├── breweries/        # Brewery management
│   ├── import/           # Data import services
│   └── search/           # Search functionality
├── config/               # Configuration management
├── middleware/           # Custom middleware
├── utils/               # Utility functions
├── types/               # TypeScript type definitions
├── app.ts               # Express app setup
└── server.ts            # Server start

🚀 Quick Start

Prerequisites

• Node.js 24+ LTS
• npm or yarn
• CouchDB (for production)

Installation

# Clone repository
git clone https://github.com/your-org/brewlog-backend.git
cd brewlog-backend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start development server
npm run dev

Environment Setup

Create a .env file with the following variables:

NODE_ENV=development
PORT=3000
CORS_ORIGIN=http://localhost:3001
LOG_LEVEL=debug
DISABLE_ANALYTICS=true
LOCAL_FIRST_MODE=true

📚 API Documentation

• Interactive Docs: http://localhost:3000/api/docs
• OpenAPI Spec: docs/openapi.yaml
• Postman Collection: docs/brewlog-api.postman_collection.json

Core Endpoints

Search

GET /api/search?q={query}

Search for beers and breweries in the catalog.

Beer Management

GET /api/beers          # List beers
GET /api/beers/:id      # Get beer details
POST /api/beers         # Create beer entry

Brewery Management

GET /api/breweries/:id  # Get brewery details

Data Import

POST /api/import/openbeerdb  # Import OpenBeerDB data

Health

GET /api/health        # Health check

🔧 Development

Scripts

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run start        # Start production server
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run lint         # Run ESLint
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm run type-check   # Run TypeScript type checking
npm run security     # Run security audit

Testing Strategy

We follow a comprehensive testing approach:

🔬 Unit Tests (60%)
    - Business logic
    - Utility functions
    - Service layer

🧪 Integration Tests (30%)
    - API endpoints
    - Database operations
    - Middleware

🌐 E2E Tests (10%)
    - Critical user workflows
    - Privacy scenarios
    - Offline functionality

Code Quality

• TypeScript: Strict mode with comprehensive type safety
• ESLint: Consistent code style
• Prettier: Automatic code formatting
• Pre-commit hooks: Automated quality checks
• Coverage: >80% minimum coverage, >90% for services

🛡️ Security & Privacy

Privacy Commitment

• ✅ No analytics or tracking - Ever
• ✅ Local-first data storage - User data stays with user
• ✅ Minimal data collection - Only what's necessary
• ✅ GDPR compliant by design - Built for privacy
• ✅ No third-party cookies - No tracking cookies
• ✅ Encrypted sensitive data - Personal notes encrypted locally

Security Measures

• 🔐 JWT-based authentication - Secure token-based auth
• 🛡️ Rate limiting - Prevent abuse
• ✅ Input validation - Zod for type-safe validation
• 🔒 SQL injection prevention - Parameterized queries
• 🌐 CORS properly configured - Strict origin controls
• 🛡️ Security headers - OWASP best practices
• 🔍 Regular security audits - Automated vulnerability scanning

Response Privacy

All API responses are filtered to remove:

• Internal database fields (_rev, syncVersion)
• Sensitive metadata
• Debug information (in production)
• User PII (unless explicitly requested)

🔄 Deployment

Development

npm run dev

Production

npm run build
npm run start

Docker (Coming Soon)

docker build -t brewlog-backend .
docker run -p 3000:3000 brewlog-backend

📊 Monitoring & Observability

Health Checks

• /api/health - Application health
• Database connectivity checks
• Memory and performance metrics

Logging

• Structured JSON logging
• Different log levels (debug, info, warn, error)
• Request/response logging (no sensitive data)
• Error tracking and alerting

Performance

• Response time monitoring
• Database query optimization
• Caching strategies
• Load balancing support

🤝 Contributing

We welcome contributions that align with our privacy-first mission! See CONTRIBUTING.md for detailed guidelines.

Development Guidelines

• Follow the Code of Conduct
• Write comprehensive tests
• Update documentation
• Consider privacy implications
• Ensure type safety
• Follow our commit message format

Privacy Guidelines for Contributors

1. Never add analytics or tracking - This is non-negotiable
2. Default to private/user-only data - Privacy should be the default
3. Minimize data collection - Only collect what's absolutely necessary
4. Use encryption for sensitive local data - Protect user data at rest
5. Consider offline functionality first - Prioritize local storage options

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenBeerDB - For the comprehensive beer catalog data
• CouchDB - For the excellent offline-sync capabilities
• RxDB - For the inspiration on offline-first architecture
• The open-source community for the amazing tools and libraries

📞 Support

• 📧 Email: api@brewlog.local
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full API Documentation
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ for privacy and offline-first beer enthusiasts