MVP Sprint documentation

GuestOps QuickDesk

Readable Project Room copy of the handoff documentation pack. GitHub access is not required. Download the ZIP if you want all Markdown files locally.

Download Markdown ZIPBack to Project Room

QA notes state exactly what was verified and what remains outside the MVP scope.

README.md

Start here

GuestOps QuickDesk — Handoff Package Delivery status GuestOps QuickDesk has been delivered as a working Dark Factory Starter MVP preview. Project Room: https://darkfactory.studio/rooms/00863318/ Live guest preview: http://guestopsquickdesk.82.25.97.242.sslip.io/ Protected operator desk: http://guestopsquickdesk.82.25.97.242.sslip.io/operator GitHub repository: https://github.com/limalimaci74/guestopsquickdeskstarter…

Read section
PROJECT_BRIEF.md

Project brief

Project Brief — GuestOps QuickDesk Purpose GuestOps QuickDesk is a focused Starter MVP for small propertymanagement teams that need a cleaner way to capture guest requests and manage operator followup during the season. Problem Guest requests often arrive through scattered channels such as WhatsApp, email, phone, or direct messages. Transfer requests, apartment issues, arrival questions, and urgent followups can be…

Read section
USER_GUIDE.md

User guide

User Guide — GuestOps QuickDesk Access Guest request form: http://guestopsquickdesk.82.25.97.242.sslip.io/ Operator desk: http://guestopsquickdesk.82.25.97.242.sslip.io/operator Project Room: https://darkfactory.studio/rooms/00863318/ Operator credentials are shared only through the approved handoff channel. The current staging preview uses a protected operator login. Guest workflow 1. Open the guest request form. 2…

Read section
QA_VERIFICATION.md

QA verification

QA Verification — GuestOps QuickDesk Current status Verdict: PASS for the stated MVP/staging scope. Verified by: Dark Factory operator. Verified at: 20260619T00:14:31Z. Environment: public VPS staging preview and merged GitHub main branch. Code and build proof Runtime proof Public guest preview opened successfully: http://guestopsquickdesk.82.25.97.242.sslip.io/ Public health endpoint returned OK: http://guestopsqui…

Read section
DEPLOYMENT_RUNBOOK.md

Deployment runbook

Deployment Runbook — GuestOps QuickDesk Current staging environment Public guest preview: http://guestopsquickdesk.82.25.97.242.sslip.io/ Operator desk: http://guestopsquickdesk.82.25.97.242.sslip.io/operator Runtime host path: /opt/guestopsquickdeskstaging/current systemd service: guestopsquickdeskstaging nginx hostname: guestopsquickdesk.82.25.97.242.sslip.io Node port: 18120 Required runtime variables PORT DATAFI…

Read section
SECURITY_PRIVACY_NOTES.md

Security and privacy notes

Security and Privacy Notes — GuestOps QuickDesk Security status This is an MVPlevel staging preview, not a full security audit or productionhardening package. Access control Guest form is public. Operator desk is protected by Basic Auth. Operator API endpoints require authentication. Successful operator authentication sets an HttpOnly session cookie for browser fetch calls. There are no peruser accounts, roles, or a…

Read section
NEXT_PHASE_ROADMAP.md

Next phase roadmap

Next Phase Roadmap — GuestOps QuickDesk Recommended next move The best next phase is production hardening plus one real guest communication channel. The MVP already proves the requestcapture and operatorreview workflow. Phase 2 should turn that workflow into something an agency can safely use with real guests. Phase 2 priorities 1. Production HTTPS deployment on a real domain. 2. Production database with backups and…

Read section
ARCHITECTURE.md

Architecture

Architecture — GuestOps QuickDesk System overview GuestOps QuickDesk is a small Node.js application with a public guest form and a protected operator desk. It is intentionally simple for the Starter MVP: one app serves the UI, API, validation, status workflow, and local JSON persistence. Components Frontend Static HTML/CSS/JavaScript served from the Node app. Public guest page at /. Protected operator desk at /opera…

Read section
API_AND_DATA_CONTRACTS.md

API and data contracts

API and Data Contracts — GuestOps QuickDesk Base URL Staging base URL: http://guestopsquickdesk.82.25.97.242.sslip.io Authentication model Public endpoints: health check and guest request creation. Protected endpoints: operator pages, request list, request detail, and status update. Operator authentication: Basic Auth followed by an HttpOnly operator session cookie for browser API calls. Endpoints GET /api/health Pu…

Read section
HANDOFF_CHECKLIST.md

Handoff checklist

Handoff Checklist — GuestOps QuickDesk Delivery readiness [x] Project Room is available: https://darkfactory.studio/rooms/00863318/ [x] Live guest preview is available: http://guestopsquickdesk.82.25.97.242.sslip.io/ [x] Protected operator desk is available: http://guestopsquickdesk.82.25.97.242.sslip.io/operator [x] GitHub repository is available: https://github.com/limalimaci74/guestopsquickdeskstartermvp [x] READ…

Read section
PHASE_2_BACKLOG.md

Phase 2 backlog

Phase 2 Backlog — GuestOps QuickDesk Product backlog Guest tracking link for request status. Operator filters by property, status, date, and urgency. Assignment to staff or external partners. Internal notes separated from guestvisible notes. Message templates for common replies. Daily arrival and unresolvedrequest dashboard. Basic SLA timers and overdue alerts. Property/reservation import. Integration backlog WhatsA…

Read section

README.md

# GuestOps QuickDesk — Handoff Package

## Delivery status

GuestOps QuickDesk has been delivered as a working Dark Factory Starter MVP preview.

- Project Room: https://darkfactory.studio/rooms/00863318/
- Live guest preview: http://guestops-quickdesk.82.25.97.242.sslip.io/
- Protected operator desk: http://guestops-quickdesk.82.25.97.242.sslip.io/operator
- GitHub repository: https://github.com/limalimaci74/guestops-quickdesk-starter-mvp
- Verification status: PASS for the stated MVP/staging scope
- Last handoff refresh: 2026-06-19T00:14:31Z

## What this package contains

This package explains what was built, how to use it, what was verified, how it is deployed, what the API contract looks like, what security boundaries apply, and what should move into Phase 2.

## What the MVP proves

A guest can submit a structured request through a public form. An operator can open a protected desk, review incoming requests, inspect details, update status, and follow a checklist until the request is completed.

## Scope boundary

This is a working staging preview, not a production-hardened SaaS platform. No live email, SMS, WhatsApp, payment, CRM, PMS, or government-system integration is active in this Starter sprint.

## Recommended reading order

1. `PROJECT_BRIEF.md`
2. `USER_GUIDE.md`
3. `QA_VERIFICATION.md`
4. `DEPLOYMENT_RUNBOOK.md`
5. `SECURITY_PRIVACY_NOTES.md`
6. `NEXT_PHASE_ROADMAP.md`

PROJECT_BRIEF.md

# Project Brief — GuestOps QuickDesk

## Purpose

GuestOps QuickDesk is a focused Starter MVP for small property-management teams that need a cleaner way to capture guest requests and manage operator follow-up during the season.

## Problem

Guest requests often arrive through scattered channels such as WhatsApp, email, phone, or direct messages. Transfer requests, apartment issues, arrival questions, and urgent follow-ups can be copied manually into notes or task lists. During peak season this creates status confusion, delayed responses, and missed ownership.

## Target user

- Primary user: an operator at a small property-management agency.
- Buyer / decision maker: the founder or operations owner of the agency.
- Guest-facing user: a guest who needs to submit a clear request without knowing the internal workflow.

## MVP promise

A guest can submit a structured request. The operator can see it in a protected desk, open the detail page, update status, and follow a simple checklist until the request is done.

## Delivered scope

- Public guest request form.
- Request categories for transfer, apartment issue, arrival question, and other guest needs.
- Required field validation.
- Confirmation screen with request reference.
- Protected operator desk.
- Request list sorted by newest first.
- Request detail page.
- Status workflow: New, Acknowledged, In progress, Waiting on guest, Done.
- Follow-up checklist for operator handling.
- Local JSON persistence for the staging preview.
- Public Project Room handoff documentation.

## Not included in this Starter sprint

- Production custom-domain HTTPS deployment.
- Production database, backups, and retention policy.
- Multi-user team accounts and role-based access control.
- Real WhatsApp, SMS, email, PMS, CRM, payment, or eVisitor integration.
- Automated dispatch or provider messaging.
- SLA analytics, reporting, or escalation automation.
- Native mobile app.

## Acceptance criteria

- The guest can submit a realistic request from the public preview.
- The operator can see and manage that request from a protected desk.
- The status workflow is visible and usable.
- The preview is deployed and reachable through a public URL.
- Known MVP limitations are documented clearly.
- QA evidence is recorded in `QA_VERIFICATION.md`.

USER_GUIDE.md

# User Guide — GuestOps QuickDesk

## Access

- Guest request form: http://guestops-quickdesk.82.25.97.242.sslip.io/
- Operator desk: http://guestops-quickdesk.82.25.97.242.sslip.io/operator
- Project Room: https://darkfactory.studio/rooms/00863318/

Operator credentials are shared only through the approved handoff channel. The current staging preview uses a protected operator login.

## Guest workflow

1. Open the guest request form.
2. Enter the guest name.
3. Enter the property or unit name.
4. Select the request type.
5. Enter the needed date or time.
6. Describe the request.
7. Choose the preferred contact method.
8. Add contact details.
9. Submit the request.
10. Save the request reference shown on the confirmation screen.

## Operator workflow

1. Open the operator desk.
2. Sign in with the shared operator credentials.
3. Review the request table.
4. Open the request detail page.
5. Read guest details, request type, timing, and message.
6. Move the request through the status workflow.
7. Use the follow-up checklist to keep handling consistent.
8. Mark the request Done when the operational follow-up is complete.

## What success looks like

- A guest does not need to send an unstructured message to start the workflow.
- The operator sees a clear queue instead of scattered messages.
- Each request has a reference and a visible status.
- The team can use the preview to discuss what should be automated or hardened next.

## Known user-facing limitations

- The preview does not send real notifications to guests or staff.
- The operator must manually check and handle requests.
- The app does not yet support team accounts or per-property permissions.
- The preview stores MVP data on the server filesystem, not in a production database.

QA_VERIFICATION.md

# QA Verification — GuestOps QuickDesk

## Current status

- Verdict: PASS for the stated MVP/staging scope.
- Verified by: Dark Factory operator.
- Verified at: 2026-06-19T00:14:31Z.
- Environment: public VPS staging preview and merged GitHub main branch.

## Code and build proof

```bash
cd /var/lib/docker/volumes/deploy_archon_data/_data/workspaces/limalimaci74/guestops-quickdesk-starter-mvp/source && npm test
# exit_code=0 — 27 passed, 0 failed

cd /var/lib/docker/volumes/deploy_archon_data/_data/workspaces/limalimaci74/guestops-quickdesk-starter-mvp/source && npm run build
# exit_code=0 — build check passed
```

## Runtime proof

- Public guest preview opened successfully: http://guestops-quickdesk.82.25.97.242.sslip.io/
- Public health endpoint returned OK: `http://guestops-quickdesk.82.25.97.242.sslip.io/api/health`
- Guest request creation returned HTTP 201.
- Unauthenticated operator page returned HTTP 401.
- Unauthenticated operator API returned HTTP 401.
- Authenticated operator page returned HTTP 200.
- Authenticated operator API returned HTTP 200.
- Operator status update returned HTTP 200.

## Browser proof

- Guest page rendered the request form.
- Guest header did not expose an operator-desk link.
- Browser form submission reached a confirmation screen.
- Operator desk rendered the request table after authentication.
- Browser console was checked after the final fix and showed no JavaScript errors.

## Security correction made during QA

Initial QA found that the operator desk/API were public. That was a real blocker. It was fixed before final handoff:

- Operator page now requires Basic Auth.
- Operator API now requires authentication.
- Successful operator authentication sets an HttpOnly session cookie for browser fetch calls.
- Guest page no longer links publicly to the operator desk.
- Regression coverage was added for the operator auth gate.

## Remaining limitations

- The preview is HTTP staging on an sslip.io hostname, not custom-domain HTTPS production.
- Operator login is shared Basic Auth plus an HttpOnly cookie; production identity and roles are Phase 2.
- Persistence is local JSON on the VPS; production database and backups are Phase 2.
- No real email, SMS, WhatsApp, payment, PMS, CRM, or eVisitor provider is connected.
- No automated dispatch occurs; operator follow-up is manual.

## Final QA boundary

The MVP is delivered as a working staging preview. It should not be represented as a production-hardened platform until production hosting, identity, database, monitoring, backups, and provider integrations are implemented and verified.

DEPLOYMENT_RUNBOOK.md

# Deployment Runbook — GuestOps QuickDesk

## Current staging environment

- Public guest preview: http://guestops-quickdesk.82.25.97.242.sslip.io/
- Operator desk: http://guestops-quickdesk.82.25.97.242.sslip.io/operator
- Runtime host path: `/opt/guestops-quickdesk-staging/current`
- systemd service: `guestops-quickdesk-staging`
- nginx hostname: `guestops-quickdesk.82.25.97.242.sslip.io`
- Node port: `18120`

## Required runtime variables

- `PORT`
- `DATA_FILE`
- `OPERATOR_PASSWORD`
- `NODE_ENV`

Secret values must stay in the protected server environment file and must not be committed to GitHub or written into public documentation.

## Local run

```bash
npm install
OPERATOR_PASSWORD='replace-with-local-password' DATA_FILE='./data/requests.json' npm run dev
```

## Test and build verification

```bash
npm test
npm run build
```

## Current deploy pattern

1. Build or update the source from the merged main branch.
2. Copy the release into `/opt/guestops-quickdesk-staging/releases/<timestamp>`.
3. Preserve the protected `.env` file and `data/` directory.
4. Update `/opt/guestops-quickdesk-staging/current` to point at the new release.
5. Restart the service:

```bash
systemctl restart guestops-quickdesk-staging
systemctl status guestops-quickdesk-staging --no-pager
```

## Verify after deploy

```bash
curl -sS http://127.0.0.1:18120/api/health
curl -sS http://guestops-quickdesk.82.25.97.242.sslip.io/api/health
```

Then verify in a browser:

- guest form opens;
- guest request can be submitted;
- operator desk requires login;
- operator desk loads request data after login;
- request status can be changed;
- browser console has no JavaScript errors.

## Rollback

1. List previous releases in `/opt/guestops-quickdesk-staging/releases`.
2. Repoint `/opt/guestops-quickdesk-staging/current` to the previous release.
3. Restart `guestops-quickdesk-staging`.
4. Re-run health and browser smoke checks.

## Production note

This runbook describes the current staging preview. A production deployment should add custom-domain HTTPS, a production database, backups, monitoring, secure identity, rate limits, and provider configuration.

SECURITY_PRIVACY_NOTES.md

# Security and Privacy Notes — GuestOps QuickDesk

## Security status

This is an MVP-level staging preview, not a full security audit or production-hardening package.

## Access control

- Guest form is public.
- Operator desk is protected by Basic Auth.
- Operator API endpoints require authentication.
- Successful operator authentication sets an HttpOnly session cookie for browser fetch calls.
- There are no per-user accounts, roles, or audit trails yet.

## Secrets

- Operator password is stored in the protected server environment file.
- The password is not committed to GitHub.
- Public documentation lists required variable names but not secret values.

## Personal data

The guest request form can collect:

- guest name;
- property or unit;
- request details;
- needed time;
- contact method;
- contact detail.

For production use, the owner should define retention, deletion, export, and access policies before real guest data is processed.

## Logging and storage

- MVP request data is stored in a local JSON file on the server.
- Production use should move to a managed database with backups and access controls.
- Avoid entering real sensitive guest data into the staging preview unless explicitly approved.

## Known security gaps before production

- Shared operator login should be replaced with real user accounts.
- Role-based access control is not implemented.
- CSRF/session hardening is not production-grade.
- Rate limiting and abuse protection are not implemented.
- Production monitoring and alerting are not implemented.
- Backup and restore verification are not implemented.
- Dependency vulnerability review should be run before production hardening is declared complete.

NEXT_PHASE_ROADMAP.md

# Next Phase Roadmap — GuestOps QuickDesk

## Recommended next move

The best next phase is production hardening plus one real guest communication channel. The MVP already proves the request-capture and operator-review workflow. Phase 2 should turn that workflow into something an agency can safely use with real guests.

## Phase 2 priorities

1. Production HTTPS deployment on a real domain.
2. Production database with backups and restore testing.
3. Proper operator accounts and roles.
4. Real message intake or notification channel, preferably WhatsApp/SMS through a regional provider such as Infobip if the Croatian hospitality workflow is the target.
5. Property and reservation context so requests can be tied to units and stays.
6. Basic SLA/status reporting for unanswered or aging requests.

## Product upgrades

- Guest request tracking link.
- Operator filters by property, status, date, and urgency.
- Assignment to staff members.
- Internal notes and visible guest notes separated clearly.
- Message templates for common guest replies.
- Daily operations summary for arrivals and unresolved requests.

## Technical upgrades

- PostgreSQL or another managed production database.
- Migration system.
- CI/CD pipeline.
- Structured logs and monitoring.
- Rate limiting and abuse protection.
- Secrets management.
- Backup and rollback runbook.

## Commercial framing

- Production Hardening: from 2,000 EUR+.
- Phase 2 Guest Messaging Upgrade: 2,500–4,500 EUR.
- AI Operator / Copilot layer: 4,000–8,000 EUR depending on integrations and approval flow.

## Decision filter

Approve a Phase 2 item only if it improves response speed, reduces manual copying, lowers missed-request risk, supports revenue retention, or is tied to a signed operational use case.

ARCHITECTURE.md

# Architecture — GuestOps QuickDesk

## System overview

GuestOps QuickDesk is a small Node.js application with a public guest form and a protected operator desk. It is intentionally simple for the Starter MVP: one app serves the UI, API, validation, status workflow, and local JSON persistence.

## Components

### Frontend

- Static HTML/CSS/JavaScript served from the Node app.
- Public guest page at `/`.
- Protected operator desk at `/operator`.
- Operator detail page at `/operator/request/<id>`.
- Browser fetch calls submit guest requests and update operator statuses.

### Backend

- Node.js HTTP server.
- Request validation and status workflow in application code.
- Basic Auth gate for operator pages and operator API.
- HttpOnly operator session cookie after successful Basic Auth so browser API calls work reliably.

### Data layer

- MVP persistence is a local JSON file.
- Main entity: guest request.
- Stored fields include guest name, property, request type, needed time, message, contact method, contact detail, status, reference, created time, and updated time.

### Deployment layer

- systemd service: `guestops-quickdesk-staging`.
- Runtime path: `/opt/guestops-quickdesk-staging/current`.
- nginx routes the public hostname to the local Node service.

## Main request flow

1. Guest opens the public form.
2. Browser validates required inputs.
3. `POST /api/requests` creates a request.
4. Server validates and writes the request to local JSON storage.
5. Guest sees a confirmation reference.
6. Operator opens the protected desk.
7. Operator reviews the queue and updates status through the protected API.

## Boundaries

- Guest-facing route: `/`.
- Operator/admin routes: `/operator` and `/operator/request/<id>`.
- Public API: `POST /api/requests` and `GET /api/health`.
- Protected API: request list, request detail, and status update endpoints.
- Manual workflow remains required for actual guest communication and operational dispatch.

## Architecture risks

- Local JSON storage is acceptable for the MVP preview but not for production.
- Shared operator credentials are acceptable for a controlled preview but not for production team use.
- No queue, retry system, notification worker, or external provider integration exists yet.
- Monitoring and backup coverage are not production-grade.

API_AND_DATA_CONTRACTS.md

# API and Data Contracts — GuestOps QuickDesk

## Base URL

- Staging base URL: http://guestops-quickdesk.82.25.97.242.sslip.io

## Authentication model

- Public endpoints: health check and guest request creation.
- Protected endpoints: operator pages, request list, request detail, and status update.
- Operator authentication: Basic Auth followed by an HttpOnly operator session cookie for browser API calls.

## Endpoints

### `GET /api/health`

Purpose: runtime health check.

Expected response:

```json
{"status":"ok"}
```

### `POST /api/requests`

Purpose: create a guest request.

Required payload fields:

```json
{
  "guestName": "string",
  "property": "string",
  "requestType": "transfer | apartment_issue | arrival_question | other",
  "neededAt": "string",
  "message": "string",
  "contactMethod": "email | phone | whatsapp | in_person",
  "contactDetail": "string"
}
```

Success response: HTTP 201 with the created request and reference.

### `GET /api/requests`

Purpose: list request summaries for the operator desk.

Auth: required.

### `GET /api/requests/:id`

Purpose: load one request detail page.

Auth: required.

### `POST /api/requests/:id/status`

Purpose: update request status.

Auth: required.

Payload:

```json
{"status":"new | acknowledged | in_progress | waiting_on_guest | done"}
```

## Request entity

```json
{
  "id": "string",
  "reference": "GQ-YYYY-NNNN",
  "guestName": "string",
  "property": "string",
  "requestType": "string",
  "neededAt": "string",
  "message": "string",
  "contactMethod": "string",
  "contactDetail": "string",
  "status": "string",
  "createdAt": "ISO-8601 timestamp",
  "updatedAt": "ISO-8601 timestamp"
}
```

## Provider boundaries

No external provider is called by the current MVP. Email, SMS, WhatsApp, PMS, CRM, payment, and eVisitor integrations are out of scope for this delivered Starter preview.

HANDOFF_CHECKLIST.md

# Handoff Checklist — GuestOps QuickDesk

## Delivery readiness

- [x] Project Room is available: https://darkfactory.studio/rooms/00863318/
- [x] Live guest preview is available: http://guestops-quickdesk.82.25.97.242.sslip.io/
- [x] Protected operator desk is available: http://guestops-quickdesk.82.25.97.242.sslip.io/operator
- [x] GitHub repository is available: https://github.com/limalimaci74/guestops-quickdesk-starter-mvp
- [x] README and handoff documents are available in English.
- [x] QA verification contains real command, runtime, and browser proof.
- [x] Known limitations are written down.
- [x] Operator auth blocker found during QA was fixed.

## Client/founder review

- [ ] Review the live guest form.
- [ ] Review the protected operator desk.
- [ ] Confirm whether the request categories match the intended first workflow.
- [ ] Decide whether Phase 2 should focus on production hardening, messaging integration, or property/reservation context first.

## Technical handoff

- [x] Runtime service name documented.
- [x] Deployment path documented.
- [x] Required environment variables listed without secret values.
- [x] API endpoints documented.
- [x] Rollback path documented.
- [x] Security and privacy limits documented.

## Final handoff status

- Status: READY for MVP/staging review.
- Owner: Dark Factory delivery team.
- Remaining blockers for production: custom-domain HTTPS, production identity, production database, monitoring, backups, and real communication provider integration.

PHASE_2_BACKLOG.md

# Phase 2 Backlog — GuestOps QuickDesk

## Product backlog

- Guest tracking link for request status.
- Operator filters by property, status, date, and urgency.
- Assignment to staff or external partners.
- Internal notes separated from guest-visible notes.
- Message templates for common replies.
- Daily arrival and unresolved-request dashboard.
- Basic SLA timers and overdue alerts.
- Property/reservation import.

## Integration backlog

- WhatsApp intake or notification through an approved provider.
- SMS fallback for urgent or non-WhatsApp guests.
- Email intake parser.
- PMS/booking source import.
- CRM or helpdesk export.
- eVisitor-related context only if commercially and legally scoped.

## Technical backlog

- Production database.
- Migration system.
- Automated deployment pipeline.
- Custom-domain HTTPS.
- Monitoring and alerting.
- Backup and restore verification.
- Rate limiting.
- Structured audit log.
- User accounts and roles.

## Commercial decision rule

Do not promote backlog items because they are interesting. Promote them only when they support revenue, operational savings, response speed, risk reduction, or a signed follow-on scope.