Queue-North-Website/README.md

# Queue North Website

## Objective

Queue North Website is the modern rebuild of the Queue North Technologies business website.

The goal is to replace the current static early-2000s-style HTML/CSS/JS site with a polished 2026 business website that clearly presents Queue North as a trustworthy communications, contact center, networking, and managed support partner.

The site should feel:

- Bright and professional
- Modern but not flashy
- Business-first, not cyber/gaming/crypto
- Easy to navigate
- Clear about Queue North's 8x8 partnership and service expertise
- Optimized for consultation and support request conversion

## Target Stack

- **Vite** — build tool, not Next.js
- **React** — SPA frontend
- **React Router** — client-side routing
- **Tailwind CSS** — utility-first styling
- **shadcn/ui** — component primitives
- **Sonner** — toast notifications
- **TanStack Query** — server state management
- **Express** — backend API
- **better-sqlite3** — SQLite database

## Layout Direction

The design direction is a light-first B2B technology layout with strategic dark navy sections.

Primary structure:

1. **Hero**
   - Dark navy section
   - Clear headline and value proposition
   - Primary CTA: `Request Consultation`
   - Secondary CTA: `Explore Services`
   - Trust chips: 8x8 Certified Partner, Veteran Owned, 25+ Years Experience, SMB to Enterprise

2. **Trust / Certification Bar**
   - Light section
   - Reinforces 8x8 partner credibility

3. **Services Preview**
   - White cards on a bright background
   - Concise service explanations
   - Links to service detail pages

4. **Why Queue North**
   - Three-pillar section:
     - Architecture
     - Deployment
     - Lifecycle Support

5. **Industries**
   - Healthcare
   - Retail
   - Manufacturing
   - Education & Finance

6. **Final CTA**
   - Dark navy conversion band
   - Consultation-focused message

## Planned Routes

```txt
/
/about
/services
/services/unified-communications
/services/contact-center
/services/managed-support
/services/consulting-training
/services/infrastructure-cabling
/services/wireless-access
/services/local-networking
/industries
/industries/healthcare
/industries/retail
/industries/manufacturing
/industries/education-finance
/8x8
/contact
/support
```

## Overhaul Phases

Version numbers correlate directly to the active phase:

- **Phase 1 — Stack Scaffold**: `0.1.x` ✅ Complete
  - ~~Vite + React app foundation~~ ✅
  - ~~Tailwind CSS setup~~ ✅
  - ~~shadcn/ui-style primitives~~ ✅
  - ~~React Router~~ ✅
  - ~~Express backend~~ ✅
  - ~~better-sqlite3 database~~ ✅
  - ~~Initial API health/contact/support paths~~ ✅

- **Phase 2 — Layout Rebuild**: `0.2.x` ✅ Complete
  - ~~App shell: Header, Footer, layout wrapper, mobile nav~~ ✅
  - ~~Route pages fully built and navigable~~ ✅
  - ~~Existing business content ported into React~~ ✅
  - ~~Repeated service/industry content moved into data files~~ ✅
  - ~~Static hash routing fully replaced by React Router~~ ✅

- **Phase 3 — Visual Overhaul**: `0.3.x` ✅ Complete
  - ~~Modern light-first business design~~ ✅
  - ~~Tailwind theme polish~~ ✅
  - ~~Typography, spacing, radius, shadows, and responsive rhythm~~ ✅
  - ~~Refined service/industry cards and CTA sections~~ ✅
  - ~~Mobile-first layout polish~~ ✅

- **Phase 4 — Forms + Backend Hardening**: `0.4.x` 🔄 In Progress
  - ~~Contact and support forms fully wired to Express~~ ✅
  - ~~SQLite persistence verified~~ ✅
  - ~~Client-side validation + Sonner feedback~~ ✅
  - ~~Server-side validation + input sanitization~~ ✅
  - ~~Optional Zoho forwarding layer~~ ✅
  - Backend/API hardening as needed

- **Phase 5 — Verification + Release Readiness**: `0.5.x`
  - Build/runtime verification
  - Route and form testing
  - Accessibility checks
  - Documentation and release cleanup
  - Final push to `dev` for the completed phase

Patch versions increment for completed task batches after the full pipeline finishes. Dispatch a task batch, run it through the required agents, then push that completed batch once. Example: Docker task batch goes through Neo → Private Hudson → Bishop → Ripley, then pushes as `0.2.1`. Notes/tags should use the version number only.

## Backend Goals

Initial API endpoints:

```txt
GET  /api/health
POST /api/leads
POST /api/support
```

Initial SQLite tables:

- `leads`
- `support_requests`

Contact and support forms should submit through Express, save to SQLite, and show user feedback with Sonner.

## Agent Plan

The overhaul is handled through the agent pipeline below:

1. **Scarlett** — design system, Tailwind/shadcn layout direction, responsive polish, accessibility review
2. **Neo** — Vite/React implementation, Express API, SQLite/database work, build-system changes
3. **Private Hudson** — security review for API routes, form handling, validation, data exposure, dependency risks, and backend hardening
4. **Scarlett** — UI polish pass after implementation changes
5. **Bishop** — build/runtime verification, route checks, documentation verification, version consistency
6. **Ripley** — final local checks, commit, tag, and push to `dev`

Agents do not touch git. Ripley owns all commits, tags, and pushes.

## Batch Pipeline Rule

Work is dispatched as task batches. A batch runs through the required agents, then Ripley pushes that completed batch once.

Example Docker batch:

```txt
Neo → Private Hudson → Bishop → Ripley
```

The whole Docker batch is one checkpoint: `0.2.1`.

Do not increment the patch version for each individual agent inside the same batch. Increment only after the full task batch finishes and is ready to push.

Notes, tags, and checkpoint labels should use only the version number, such as `0.2.1`.

## Design Source of Truth

See [OVERHAUL_PLAN.md](./OVERHAUL_PLAN.md) for the full rebuild plan and Scarlett's design implementation brief.

## Docker Deployment

The application can be containerized using Docker for consistent deployment across environments.

### Prerequisites

- Docker (v20+)
- Docker Compose (v2+)

### Quick Start

#### Using Docker Compose (Recommended)

```bash
# Build and start the container
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop the container
npm run docker:compose:down
```

#### Manual Docker Build

```bash
# Build the image
npm run docker:build

# Run the container
npm run docker:run
```

### Environment Variables

Set the following in the `.env` file (not included in image by default):

```env
NODE_ENV=production
SERVER_PORT=3001
```

### Data Persistence

SQLite database is persisted in the `./db` directory. Data will survive container restarts.

**Note on data persistence:**

The application uses Docker named volumes (`queuenorth-db` and `queuenorth-logs`) to persist data. Docker manages the ownership and permissions of these volumes automatically, so no manual setup is required.

If you prefer to use host bind mounts instead, ensure your host `./db` and `./logs` directories are owned by UID 1001:

```bash
mkdir -p ./db ./logs
sudo chown -R 1001:1001 ./db ./logs
```

If you encounter "unable to open database file" errors, verify the host directory is writable by the container's UID (1001) or use named volumes as shown above.

### Health Check

The container includes a health check at `/api/health`. A healthy container returns:

```json
{"status":"ok","timestamp":"2026-05-12T..."}
```

### Ports

- Backend API: `3001` (host) → `3001` (container)

### Build Optimization

The `.dockerignore` excludes:
- `node_modules` (reinstalled in container)
- `dist` (built in container)
- `db/` (mounted as volume)
- `.git`, logs, private docs

This ensures minimal image size and reproducible builds.