docs: Improve readme

2026-06-06 23:25:59 +05:30
parent 77349f2b90
commit 012db524cb
1 changed files with 57 additions and 22 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,52 @@
-# Brew Application
+<p align="center">
+  <img src="public/brew_favicons/brew_1024.png" alt="Brew Journal Logo" width="256" height="256" />
+</p>

-Welcome to the **Brew** application! This project features a React + Vite frontend and a Node.js Express + PostgreSQL backend.
+<h1 align="center">Brew Journal</h1>
+
+<p align="center">
+  A beautiful, offline-first coffee logbook and brewing companion designed to track, refine, and perfect your daily coffee rituals.
+</p>
+
+<p align="center">
+  A fully functioning instance of the application is available at <a href="https://brew.adityagupta.dev">brew.adityagupta.dev</a>.
+</p>
+
+<p align="center">
+  <a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19.0-61DAFB?style=flat-square&logo=react&logoColor=black" alt="React" /></a>
+  <a href="https://vite.dev/"><img src="https://img.shields.io/badge/Vite-8.0-646CFF?style=flat-square&logo=vite&logoColor=white" alt="Vite" /></a>
+  <a href="https://tailwindcss.com/"><img src="https://img.shields.io/badge/Tailwind_CSS-4.0-38B2AC?style=flat-square&logo=tailwind-css&logoColor=white" alt="TailwindCSS" /></a>
+  <a href="https://expressjs.com/"><img src="https://img.shields.io/badge/Express-5.2-000000?style=flat-square&logo=express&logoColor=white" alt="Express" /></a>
+  <a href="https://www.postgresql.org/"><img src="https://img.shields.io/badge/PostgreSQL-14+-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL" /></a>
+  <img src="https://img.shields.io/badge/PWA-Ready-orange?style=flat-square&logo=progressive-web-apps&logoColor=white" alt="PWA Ready" />
+  <img src="https://img.shields.io/badge/License-ISC-blue?style=flat-square" alt="License" />
+</p>
+
+## Screenshots
+
+<p align="center">
+  <!-- Place your app screenshots here once available -->
+  <em>Screenshots coming soon!</em>
+</p>
+
+<!--
+<p align="center">
+  <img src="path/to/dashboard.png" alt="Brew Journal Dashboard" width="800" />
+</p>
+<p align="center">
+  <img src="path/to/mobile_dashboard.png" alt="Mobile Dashboard View" width="280" style="margin-right: 10px;" />
+  <img src="path/to/brew_form.png" alt="Brew Logging View" width="280" />
+</p>
+-->
+
+## Features
+
+- **Coffee Bean Inventory & Recipes**: Keep track of your coffee beans, including roasters, roast levels, origins, processing methods, and personal tasting notes. Save custom brewing parameters for every bean.
+- **Detailed Brew Logging**: Record every brewing session with precise details: brew method (Pour Over, Espresso, Cold Brew, etc.), grind size, water temperature, brew ratio, and brew time. Grade your cups with detailed taste notes and reviews.
+- **Offline-First Sync Engine**: Fully functional offline using local browser storage (`localStorage`). Automatically merges and syncs to a PostgreSQL database via the Express backend when connectivity is restored, using a conflict-resolution system.
+- **Mobile & PWA Ready**: Designed with a sleek, mobile-first responsive layout. Features a custom install prompt modal (including iOS specific guidelines) so you can run it as a standalone app.
+- **Modern Dark & Light Mode**: Clean, warm, custom-tailored interface matching the espresso color palette. Persistent theme switching based on user preference.
+- **Secure User Accounts**: Personal user profiles backed by JSON Web Tokens (JWT) and `bcrypt` password hashing, plus backend API rate-limiting.

 ## Architecture Overview

@@ -14,8 +60,6 @@ The codebase is split into two main sections:
  - [server/index.js](file:///home/sortedcord/Projects/brew/server/index.js) (Express application setup, routes, and authentication middleware)
  - [server/db.js](file:///home/sortedcord/Projects/brew/server/db.js) (PostgreSQL connection and table initialization)

---
-
 ## Prerequisites

 Make sure you have the following installed on your system:
@@ -23,15 +67,15 @@ Make sure you have the following installed on your system:
 - **npm** (v9.x or higher)
 - **PostgreSQL** (v14 or higher)

---
+## Getting Started

-## 1. Database Setup (PostgreSQL)
+### 1. Database Setup (PostgreSQL)

 You need a running PostgreSQL database instance. Follow the steps below based on your operating system:

-### Installing PostgreSQL
+#### Installing PostgreSQL

-#### Linux (Debian/Ubuntu)
+##### Linux (Debian/Ubuntu)
 ```bash
 sudo apt update
 sudo apt install postgresql postgresql-contrib
@@ -42,18 +86,16 @@ sudo systemctl start postgresql
 sudo systemctl enable postgresql
 ```

-#### macOS (using Homebrew)
+##### macOS (using Homebrew)
 ```bash
 brew install postgresql
 brew services start postgresql
 ```

-#### Windows
+##### Windows
 Download and run the interactive installer from the [Official PostgreSQL Downloads page](https://www.postgresql.org/download/windows/).

---
-
-### Creating the Database and User
+##### Creating the Database and User

 1. Log into the PostgreSQL interactive terminal as the superuser `postgres`:
   ```bash
@@ -87,9 +129,7 @@ Download and run the interactive installer from the [Official PostgreSQL Downloa
 > [!NOTE]
 > Database tables (such as `users`) are initialized automatically when you start the backend server, as defined in [server/db.js](file:///home/sortedcord/Projects/brew/server/db.js).

---
-
-## 2. Backend Setup
+### 2. Backend Setup

 1. Navigate to the backend directory:
   ```bash
@@ -120,9 +160,7 @@ Download and run the interactive installer from the [Official PostgreSQL Downloa
   Server running on port 5000
   ```

---
-
-## 3. Frontend Setup
+### 3. Frontend Setup

 1. Open a new terminal window/tab and navigate to the project root directory:
   ```bash
@@ -141,8 +179,6 @@ Download and run the interactive installer from the [Official PostgreSQL Downloa

 4. Open your browser and navigate to the local URL printed in the console (usually `http://localhost:5173`).

---
-
 ## Production Deployment

 When deploying the Brew application to a production environment, follow these guidelines for security, reliability, and performance:
@@ -205,4 +241,3 @@ When deploying the Brew application to a production environment, follow these gu

 > [!IMPORTANT]
 > **HTTPS Required for PWAs**: For security reasons, web browsers will only install Progressive Web Apps (PWAs) and register Service Workers when served over a secure connection (`HTTPS`). Make sure to set up an SSL certificate (e.g., via Let's Encrypt / Certbot) for your production deployment domain. Local development on `localhost` or `127.0.0.1` is exempt and will work over HTTP.
-