The Shamrock Inn — Pub Manager

A fully self-contained, single-page web application for managing day-to-day pub operations. Built as a single HTML file with all CSS and JavaScript inline — it requires no build step, no server-side logic, no external dependencies, and no CDN resources. Simply open index.html in a browser and start managing your pub.

---

What the Application Does

The Shamrock Inn Pub Manager provides six integrated modules accessible via a tab navigation interface:

Module	Description
Staff Rota	Create and edit weekly shift schedules for named employees with role assignments (bar staff, floor, kitchen, management). Export payroll as a CSV with employee name, role, total hours, hourly rate, and gross pay.
Stock Tracking	Track bar inventory across item types — kegs (with pints-per-keg conversion), spirits (with measures-per-bottle conversion), mixers, and sundries. Set par levels and receive visual low-stock warnings when quantities fall below configured thresholds. Includes a stock-take reconciliation view.
Supplier Ordering	Maintain a supplier directory, create purchase orders with multiple line items (product, quantity, unit cost), and track each order through its full lifecycle: draft → sent → partially received → fully received.
Events / Calendar	Monthly calendar grid for scheduling pub events — live music, quiz nights, sports screenings, private bookings — with full create, read, update, and delete (CRUD) operations on each event entry.
POS Overlay	Record sale transactions by selecting a product or category and quantity. Displays a running daily sales total in euros and automatically decrements corresponding stock levels on each recorded sale.
Shrinkage & Wastage	Record categorised losses (spillage, breakage, suspected theft, expired stock) linked to specific stock items. View per-product loss history and a variance report comparing theoretical stock (opening + deliveries − sales) against actual counted stock.

Additional Features

• Welcome Guide — A first-run getting-started section displayed on load, with contextual help text for each module.
• Pre-loaded Sample Data — Realistic pub inventory, staff, suppliers, and events are loaded on first open so the tool is immediately usable and demonstrable without any setup.
• Persistent Data — All data is stored in the browser's localStorage and survives page refreshes and browser restarts.
• Data Export / Import — Export all application data as JSON for backup, and re-import it to restore state.
• Storage Quota Warning — A banner alerts you when localStorage is approaching its capacity limit.

---

Prerequisites

To run the application

• A modern evergreen web browser — latest version of any of:
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari
  • Microsoft Edge

No build tools, package managers, databases, or backend services are needed.

To run the automated tests

• Node.js v18 or later

To run via Docker

• Docker (any recent version)

---

Installation

No package installation is required for the application itself. Clone or download this repository:

git clone <repository-url>
cd <repository-directory>

The application is a single file located at the root of the repository:

index.html

A copy is also maintained in src/index.html — both files are identical.

---

Running the Application

Option 1 — Open directly as a local file (simplest)

Double-click index.html, or open it from the terminal:

# macOS
open index.html

# Linux
xdg-open index.html

# Windows (Command Prompt)
start index.html

Option 2 — Serve as a static file

Use any static web server. For example:

Python (built-in):

python3 -m http.server 8000

Then open http://localhost:8000/index.html in your browser.

Node.js (npx serve):

npx serve .

Then open the URL printed in the terminal.

VS Code Live Server: Right-click index.html in the Explorer panel → Open with Live Server.

The application functions identically whether opened as a local file (file://) or served at any URL path on a static web server.

Option 3 — Docker (nginx)

A Dockerfile is included that serves the project via nginx on port 80:

# Build the image
docker build -t shamrock-pub-manager .

# Run the container
docker run -p 8080:80 shamrock-pub-manager

Then open http://localhost:8080/index.html in your browser.

---

Running the Tests

An automated test suite validates the HTML structure, feature completeness, content quality, and code correctness of the application. All 50 tests currently pass.

Prerequisites

Ensure Node.js v18+ is installed:

node --version

Run the test suite

# CommonJS version (recommended)
node test_suite.cjs

# ES Module version (equivalent)
node test_suite.js

Test results are written to test-results/qa-report.json as a structured JSON report.

What the tests cover

Category	Examples
HTML structure	Valid HTML5 document, <title>, <meta charset>, no external resource references
Module presence	All six core modules are present and reachable via tab navigation
Staff Rota	Employee fields, role options, shift scheduling, CSV export logic
Stock Tracking	Item types (keg/spirit/mixer/other), par levels, unit conversions, low-stock warnings
Supplier Ordering	Supplier directory, purchase order line items, order lifecycle statuses
Events / Calendar	Monthly grid, event types, CRUD operations, date/time fields
POS Overlay	Product selection, daily sales total, stock decrement logic
Shrinkage & Wastage	Loss categories, variance report, per-item loss history
Data persistence	localStorage read/write, data survival across sessions
Welcome & help	Getting-started section present, per-module help text
Sample data	Pre-loaded realistic data present on first open
Code quality	No alert() calls, no external API calls, storage quota safeguards
Global API	window.PubManager exposed with CRUD helpers
Data management	exportAllData(), importAllData(), clearAllData() functions present

---

Configuration Options

The Shamrock Inn Pub Manager is designed to work out of the box with zero configuration. All customisation is done through the application's UI at runtime:

Setting	Where to Configure
Stock par levels	Stock Tracking module — set per-item low-stock alert threshold
Unit conversions	Stock Tracking module — configure pints per keg, measures per spirit bottle, etc.
Employee details	Staff Rota module — add/edit employee names, roles, and hourly rates
Supplier directory	Supplier Ordering module — add/edit supplier names and contact details
Event types	Events/Calendar module — choose from live music, quiz night, sports screening, private booking, or other
Loss categories	Shrinkage & Wastage module — categorise losses as spillage, breakage, theft, or expiry

Resetting application data

All data lives in the browser's localStorage. To reset the application back to its initial state with sample data:

Option A — In-app: Use the Export / Clear Data controls available within the application UI.

Option B — Browser DevTools:

1. Open DevTools (F12 or Cmd+Option+I)
2. Navigate to Application → Local Storage → file:// (or your server origin)
3. Select and delete the relevant keys (prefixed with pubmanager_), then refresh the page.

Note: Data is scoped to the browser and origin. Different browsers or different domains (e.g. file:// vs http://localhost) maintain separate data stores.

---

Project Structure

.
├── index.html              # The complete application — single self-contained file (root copy)
├── src/
│   └── index.html          # Identical copy served from src/ path
├── tests/
│   └── test-plan.json      # Test plan specification
├── test_suite.cjs           # Automated test suite (CommonJS / Node.js)
├── test_suite.js            # Automated test suite (ES Module / Node.js)
├── test-results/
│   └── qa-report.json      # Latest test execution results
├── artifacts/               # Project planning and specification documents
│   ├── charter_v*.json      # Project charters
│   ├── prd_v1.json          # Product requirements document
│   ├── ux_spec_v1.json      # UX specification
│   └── task_plan_v1.json    # Delivery task plan
├── Dockerfile               # nginx-based container for static serving
└── README.md                # This file

---

Browser Compatibility

Tested and supported on the latest versions of:

Browser	Support
Google Chrome	✅ Supported
Mozilla Firefox	✅ Supported
Apple Safari	✅ Supported
Microsoft Edge	✅ Supported

The application uses only standard Web APIs available in all modern evergreen browsers. No polyfills or vendor-specific APIs are used.

---

Technical Constraints & Design Decisions

Constraint	Detail
Single file	All HTML, CSS, and JavaScript are inline in one .html file — no external assets
No build step	The file is the distributable; clone and open
No backend	Zero server-side logic — runs entirely in the browser
No CDN	No external scripts, stylesheets, fonts, or images loaded at runtime
Storage	localStorage only — no cookies, IndexedDB, or cloud storage
Offline-first	Works with no network connection after initial file load

---

License

See the project repository for licence details.

---

Built by HermesOrg — an orchestration of distinct AI personas working in concert. Product Manager → Designer → Engineer → QA, each contributing expertise to build something real.