Functional Specification Review

Source: Barknor_BottelaryTrailNetwork_FunctionalSpecification.pdf
Specification date: 11 July 2026
Review date: 16 July 2026

Overall assessment

The specification defines a coherent product concept and a sensible proposed first release: a menu-driven WhatsApp bot backed by a secure administration portal. The user-facing modules, most content fields, and the managing company's core administration responsibilities are described well enough to estimate at a high level.

It is not yet ready for implementation sign-off. Several choices explicitly remain with the client, the WhatsApp and membership integrations are undefined, and there are no measurable security, privacy, availability, performance, or recovery requirements. Those items are scope gates in the implementation TODO, not assumptions for the delivery team to make silently.

No application exists yet. At the time of review, this directory contained only the specification: no selected technology stack, source code, database, tests, deployment configuration, or existing backlog.

Proposed first-release baseline

The specification proposes these items for the initial release:

• Numbered WhatsApp menu and structured conversation flows
• Trail statuses and maintenance/closure information
• Annual-pass portal information and day-pass purchase locations
• Configurable member validation
• Structured maintenance-request submission and administration
• Event listings, registration, and attendance records
• Configurable event access and pass requirements
• Notice board
• Help and emergency contacts
• Secure web administration portal

The document explicitly keeps pass purchasing outside WhatsApp. Proactive trail alerts and user-submitted notices are future functionality. Maintenance status notifications and event waiting lists are conditional until the client decides otherwise.

What is specified well

• The six main bot journeys and their expected content are easy to understand.
• 0, HELP, and EMERGENCY are intended as global navigation shortcuts.
• Trail, pass-location, maintenance, event, notice, and contact fields are substantially enumerated.
• The maintenance-request and event-registration flows have useful examples.
• Administration capabilities are grouped by business area.
• Validation is intended to be configurable rather than embedded separately in each journey.
• The document calls out its open client decisions instead of presenting them as settled scope.

Decisions required before implementation

Area	Required decision	Why it matters
WhatsApp	Cloud API or provider, account/number ownership, opt-in, templates, conversation-window rules, delivery expectations, and environments	Determines the integration, operating constraints, costs, and test setup
Membership	Source system, API contract, validation identifiers, membership-expiry behavior, link duration, multiple-phone rules, and whether users can view live membership status/expiry in the bot	Determines whether configurable validation is technically possible and how personal data is handled
Access rules	Final public/member/per-item matrix for every function	The two validation descriptions in the specification are not fully consistent
Maintenance	Public or member-only, required evidence, status notifications, and operational assignee/owner	Changes the conversation flow and back-office workflow
Events	Visibility versus joining rules, pass verification, registration timing, capacity, waiting list, cancellation, attendance, invitation-only behavior, and export	Changes the event data model and the correctness rules for registration
Administration	Number of users, first-release roles, audit history, and reporting	Determines the authorization model and administration scope
Operations	Hosting, traffic assumptions, service targets, support, monitoring, backup/recovery, data residency, retention, and deletion	Required for a production design and acceptance plan
Content	Final trail names, pass URL/details, purchase locations, contacts, issue types, categories, wording, and responsible content owners	Required for user acceptance testing and launch

Conflicts and ambiguities to correct

1. The global navigation rule says 0 returns to the main menu at any stage, but the event/day-pass example uses 0 to return to the event. One behavior must be selected.
2. Section 3.1 recommends all three validation modes for each main function, while the section 11 matrix disallows per-item rules for several functions and makes help always public.
3. The text suggests that selected trail updates may be restricted, but the validation matrix says trail updates cannot be configured per item.
4. Joining an event is said to record “attendance,” while later sections correctly treat attendance as something administrators mark on the day. Joining should create a registration; attendance should be a later state change.
5. Event access rules overlap with pass requirements, but valid combinations are not defined. Day-pass verification is also absent; the example only supports self-confirmation.
6. Photographs and locations are described as “if available,” yet the client-decision section still asks whether they are compulsory.
7. Capacity appears as an event field and administration function, but capacity and waiting lists are also left as an open decision.
8. “Invitation only” has no invitation list, code, distribution, or verification workflow.
9. Viewing an event and joining it are separate configurable actions in the matrix, while the event model describes only one validation setting.
10. The administration lists differ slightly across sections: reordering day-pass locations, attendee search/removal, registration closure, available-space display, and notice publication are not repeated consistently.
11. Section 6.3 appears twice, section 12 is missing, and requirement language mixes “will,” “must,” “should,” “may,” “suggested,” and “optional” without a formal priority scheme.

Important missing requirements

Conversation behavior

• Invalid or out-of-range input
• Back, cancel, edit, timeout, abandoned-flow, and resume behavior
• Duplicate and out-of-order WhatsApp webhook delivery
• Message-delivery failure and external-service outage behavior
• Language/localisation choice
• Rules for attachments, captions, location payloads, and unsupported media

Security and privacy

• POPIA basis, consent/notice, retention, correction, export, and deletion
• Treatment of identity numbers, phone numbers, membership data, photographs, and precise locations
• Webhook verification, rate limiting, abuse controls, and secure media access
• Password policy, session expiry, password recovery, MFA decision, and authorization rules
• Security/audit logging without leaking sensitive values

Reliability and operations

• Availability, response-time, throughput, and peak-load targets
• Retry, idempotency, reference-number, and capacity-concurrency rules
• Monitoring, alerting, backups, restore target, incident response, and support ownership
• Environments, deployment approach, data migration, rollback, and stabilisation exit criteria
• WhatsApp template approval and the platform's customer-service conversation window

Acceptance and usability

• Testable acceptance criteria for each journey
• Supported browsers/devices and admin accessibility expectations
• Timezone and daylight-saving rules for events, schedules, and expiry dates
• Export format and field definitions
• Empty states, error messages, and content freshness ownership

Principal delivery risks

• Membership dependency: the MVP promises validation before the member system and API are known.
• Sensitive data: membership identifiers, phone numbers, images, and locations create privacy and security obligations that are not scoped.
• Safety: emergency details can become stale, and the bot must never imply that it dispatches emergency assistance.
• WhatsApp constraints: opt-in, templates, delivery callbacks, retries, media handling, and conversation windows affect apparently simple flows.
• Event correctness: duplicate webhooks and concurrent registrations can oversubscribe an event without database-level safeguards.
• Scope expansion: “configurable” and per-item access can multiply the administration, authorization, and test surface.

Recommended route to delivery

1. Close the scope gates at the top of the implementation TODO and issue a corrected, approved requirements baseline.
2. Produce conversation-state diagrams, an access-rule matrix, data model, integration contracts, and low-fidelity portal wireframes.
3. Build the bot shell and administration foundation, then deliver vertical slices in this order: help/trails, passes, validation, maintenance, events, notices.
4. Run end-to-end user acceptance tests with real content and the chosen WhatsApp/member-system test environments.
5. Complete security, privacy, backup/restore, load, and operational-readiness checks before a limited pilot and stabilisation period.

Minimum acceptance principles

• Restricted actions never proceed without the configured successful validation.
• Global commands behave consistently from every conversation state.
• A duplicate inbound message cannot create a duplicate request or registration.
• If event capacity is included, it is enforced atomically.
• Scheduled and expired content follows the agreed timezone.
• Every administration action is authorized; logs exclude sensitive values, and exports contain only approved necessary fields with controlled access.
• Integration failures give users a recoverable response and give operators a traceable alert.
• Content displayed in WhatsApp matches the latest published administration state.