chore: readme update

Author: agmmtoo

README.md

@@ -1,83 +1,168 @@
-## LibrarEase Web
+# LibrarEase Web
 
-A Next.js app for LibrarEase. This repo uses Yarn.
+LibrarEase Web is the Next.js frontend for LibrarEase, a library management application for books, members, subscriptions, borrows, reviews, collections, staff, and admin dashboards.
 
-**Prereqs**
+This guide is for developers who need to run the web app locally.
 
-- Node.js 18+ (or 20+ recommended)
-- Yarn (classic) — packageManager is set in `package.json`
-- Redis (local or hosted)
-- Firebase project (client SDK + Admin credentials)
+## Requirements
 
-## Quick Setup
+- Node.js 20 or newer
+- Yarn classic, managed through the version pinned in `package.json`
+- Redis, either local or hosted
+- Firebase project with client configuration and an Admin service account
+- Running LibrarEase API service, reachable from this app through `API_URL`
 
-1. Install deps
+## Local Setup
+
+### 1. Install dependencies
+
+Enable Corepack so the pinned Yarn version is used:
 
 ```bash
-yarn install
+corepack enable
+yarn install --frozen-lockfile
 ```
 
-2. Configure environment
+If your Node installation does not include Corepack, install Yarn classic and then run `yarn install --frozen-lockfile`.
+
+### 2. Create the environment file
 
-Copy the example and fill required values:
+Copy the example environment file:
 
 ```bash
-cp .env.example .env
-# or create .env.local in development
+cp .env.example .env.local
+```
+
+Fill these values before starting the app:
+
+```bash
+API_URL=http://localhost:<api-port>
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+FIREBASE_API_KEY=<firebase-web-api-key>
+FIREBASE_AUTH_DOMAIN=<firebase-auth-domain>
+FIREBASE_PROJECT_ID=<firebase-project-id>
+
+SESSION_COOKIE_NAME=<session-cookie-name>
+REFRESH_TOKEN_COOKIE_NAME=<refresh-token-cookie-name>
+LIBRARY_COOKIE_NAME=<library-cookie-name>
+CLIENT_ID=<api-client-id>
+
+GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/serviceAccountKey.json
+
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
 ```
 
-Required variables (see `.env.example` for the full list):
+`GOOGLE_APPLICATION_CREDENTIALS` must point to a Firebase Admin service account JSON file on your machine. Do not commit that file or any filled environment file.
 
-- Firebase client: `FIREBASE_API_KEY`, `FIREBASE_AUTH_DOMAIN`, `FIREBASE_PROJECT_ID`
-- Firebase Admin: `GOOGLE_APPLICATION_CREDENTIALS` (absolute path to the service account JSON)
-- Redis: `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` (optional), `REDIS_DB`
-- App URLs: `API_URL`, `NEXT_PUBLIC_APP_URL`
+The OpenTelemetry variables in `.env.example` are optional for local development.
 
-3. Start Redis
+### 3. Start Redis
 
-On macOS (Homebrew):
+With Homebrew on macOS:
 
 ```bash
 brew install redis
 brew services start redis
-# default host: localhost, port: 6379
 ```
 
-Or via Docker:
+Or with Docker:
 
 ```bash
-docker run -p 6379:6379 --name redis -d redis:7
+docker run --name librarease-redis -p 6379:6379 -d redis:7
 ```
 
-4. Run the app
+Use the same host, port, password, and database in your environment file.
+
+### 4. Start the backend API
+
+Run the LibrarEase API service separately and set `API_URL` to its base URL, for example:
+
+```bash
+API_URL=http://localhost:8000
+```
+
+In local development, this app rewrites `/api/*` requests to `${API_URL}/api/*`.
+
+### 5. Run the web app
 
 ```bash
 yarn dev
-# build & run production
-yarn build && yarn start
 ```
 
-Open http://localhost:3000 to view.
+Open [http://localhost:3000](http://localhost:3000).
+
+To run the development server with local HTTPS:
+
+```bash
+yarn devs
+```
+
+## Verify Your Setup
+
+Run these checks before opening a pull request:
+
+```bash
+yarn lint
+yarn typecheck
+yarn build
+```
+
+`yarn lint` runs Biome checks, `yarn typecheck` runs TypeScript, and `yarn build` creates a production Next.js build.
+
+## Available Scripts
+
+- `yarn dev`: start the Next.js dev server with Turbopack
+- `yarn devs`: start the dev server with experimental local HTTPS
+- `yarn devi`: start the dev server with the Node inspector enabled
+- `yarn analyze`: run Next.js bundle analysis
+- `yarn build`: create a production build
+- `yarn start`: start the production server after a build
+- `yarn lint`: run Biome checks
+- `yarn format`: format code with Biome
+- `yarn typegen`: generate Next.js route types and run TypeScript
+- `yarn typecheck`: run TypeScript without emitting files
+
+## Common Issues
+
+### The app cannot reach API routes
+
+Check that the backend API is running and that `API_URL` points to its base URL. The value should not include a trailing `/api`.
+
+### Authentication fails locally
+
+Confirm that the Firebase project values match the project used by the backend API. Also verify that the Admin service account path is absolute and readable from your shell.
+
+### Redis connection fails
+
+Confirm Redis is running on the host and port from your environment file. If you are using Docker, make sure the container is still running:
+
+```bash
+docker ps
+```
+
+### Metadata, sitemap, or absolute URLs look wrong
+
+Set `NEXT_PUBLIC_APP_URL` to the URL where the web app is being served locally, usually `http://localhost:3000`.
 
-## Scripts
+## Production Build
 
-- `yarn dev`: Next.js dev server (Turbopack)
-- `yarn build`: Production build
-- `yarn start`: Start production server
-- `yarn lint`: ESLint
-- `yarn format`: Prettier format
-- `yarn typecheck`: TypeScript type checking
+To test the production path locally:
 
-## Firebase Notes
+```bash
+yarn build
+yarn start
+```
 
-- Create a Firebase project and enable Authentication as needed
-- Place the Admin service account JSON and point `GOOGLE_APPLICATION_CREDENTIALS` to it
-- Client keys go in `FIREBASE_*` variables; do not commit secrets
+The Dockerfile builds a standalone Next.js server and exposes port `3000`.
 
-## Observability (optional)
+## Contributing
 
-If using OpenTelemetry, configure `OTEL_*` variables per `.env.example`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request expectations, code style, and contribution terms.
 
 ## License
 
-This software is licensed under the PolyForm Noncommercial License 1.0.0. See the `LICENSE` file for terms. For commercial licensing inquiries, contact: solidifyarmor@gmail.com.
+This software is licensed under the PolyForm Noncommercial License 1.0.0. See [LICENSE](LICENSE) for terms. For commercial licensing inquiries, contact solidifyarmor@gmail.com.