BrewTrace

BrewTrace is a web platform for home brewers to publish, version, and discuss brewing recipes with a collaborative community that tracks every change from the first mash to the latest tweak.

Table of Contents

• Project Description
• Tech Stack
• Getting Started Locally
• Available Scripts
• Project Scope
• Project Status
• License

Project Description

The platform empowers recipe authors to manage full version histories, capture structured brewing data, and publish clear change notes, while commenters provide targeted feedback and upvotes that feed into public rankings. Anonymous visitors can explore recipes and see engagement signals, prompting them to join the community. Activity logging and reporting features give the product team insight into growth and engagement trends across recipes and user roles.

Tech Stack

• Framework: Astro 5 with React 19 islands for dynamic experiences
• Language: TypeScript 5 with strict linting via ESLint and Prettier
• Styling: Tailwind CSS 4 with shadcn/ui primitives, class-variance-authority, tailwind-merge, and tw-animate integrations
• UI Utilities: Radix UI slot utilities and Lucide icon set
• Backend & Auth: Supabase (Postgres, Auth, RLS policies) powering recipe data, roles, and activity logging
• Tooling & CI: GitHub Actions (planned) for lint/test workflows; Node.js 22.14.0 managed via .nvmrc
• Infrastructure: Evaluation in progress between managed (Vercel + Supabase) and self-hosted (DigitalOcean + Docker) deployments per technical review

Getting Started Locally

Prerequisites

• Node.js v22.14.0 (recommended via nvm use)
• npm (bundled with Node.js)

Setup

1. Clone the repository:

   git clone https://github.com/dudzon/brewTrace.git
   cd brewTrace

2. Install dependencies:

   npm install

3. (Optional) Configure environment variables for Supabase and other services in a local .env file once those values are defined.
4. Start the development server:

   npm run dev

5. Build the production bundle:

   npm run build

6. Preview the production build locally:

   npm run preview

Available Scripts

• npm run dev – Launch the Astro development server with hot module reloading
• npm run build – Generate the optimized production build
• npm run preview – Serve the production build for local validation
• npm run astro – Run arbitrary Astro CLI commands
• npm run lint – Execute ESLint across the codebase
• npm run lint:fix – Auto-fix lint issues where possible
• npm run format – Format project files with Prettier

Project Scope

• In Scope: Email/password authentication through Supabase Auth, role-based access for recipe authors and commenters, full CRUD with version history and change notes, comment threads tied to specific versions, single upvote per user with live ranking updates, anonymous recipe browsing with filters and sorts, closed taxonomy of beer styles, password reset flow, and activity logging for engagement reporting.
• Out of Scope (MVP): External brewing API integrations, advanced moderation or abuse reporting, paid plans or monetization, community features beyond comments and votes, and multi-language user interfaces.
• Constraints: Six-week MVP window (~60–70 hours), reliance on Supabase and free-tier hosting where possible, careful management of RLS policies, and CI coverage for critical API endpoints and utilities.

Project Status

The project is in early development, translating the product requirements into implementation. The current Astro + React stack is under active evaluation to ensure it meets MVP timelines, with open questions around hosting deployment targets and the depth of AI integrations.

License

License information has not been published yet. Please contact the maintainers for guidance before distributing or reusing the code.