# Explore Uganda — interactive prototype handover

This is a responsive React/TypeScript prototype grounded in Explore Uganda SRS revision 4.3 (13 September 2026) and the eighteen UI references. It is a design and implementation starting point, not a production implementation of all 230 SRS requirements. See `traceability.csv` for explicit coverage and remaining work.

The downloadable source ZIP contains the application, reusable UI components, seed JSON, adapter contracts, tests, tokens, screen inventory and coverage register. It excludes credentials, runtime browser data, hosting identity, dependencies and nested archives.

## Start and verify

Use Node 22.13 or later and the pnpm version declared by package.json. Preserve pnpm-lock.yaml.

```
pnpm install --frozen-lockfile
pnpm dev
pnpm build
node node_modules/typescript/bin/tsc --noEmit
node tests/run.mjs
node scripts/export-demo-seed.mjs
```

The included starter's README describes supported local runtime profiles and deployment. In managed Sites environments, use its provided installation/build helpers. No application API key or payment account is required. `.env.example` intentionally contains no credentials.

## Demo data and identities

Data is created by `lib/uganda/seed.ts`, persisted under `explore-uganda-v2` in localStorage, and reset through `/demo`. The deterministic clock starts at 1 October 2026, 09:00 UTC. It changes only through the demo controls. Advance 20 minutes to expire pending holds. Refreshing preserves browser state; another browser starts an independent dataset. Reset restores all catalogue, role and policy changes.

There are 10 destinations, 8 fictional stays, 10 fictional tours, 6 fictional events, 12 fictional products, five organisation references, seven demo identities, and five example transactions spanning confirmed, pending, failed, cancelled and delivered states. One tour starts in Draft and one event in Under review, so public catalogue counts are intentionally lower than inventory counts. Examples are not real offers, ratings or availability.

| Identity | Initial role | Initial scope | Main journey |
|---|---|---|---|
| visitor@explore-uganda.demo | visitor | Own bookings and saved items | Discover, plan, book, cancel, request help |
| provider@explore-uganda.demo | provider | org-1 | Edit own listings; submit; fulfil orders |
| editor@explore-uganda.demo | editor | All assigned records | Content drafts and submissions |
| reviewer@explore-uganda.demo | reviewer | All assigned records | Review and publish |
| finance@explore-uganda.demo | finance | Reports and refund operations | Financial summary and cancellation refunds |
| support@explore-uganda.demo | support | Support queue | Resolve sample requests |
| admin@explore-uganda.demo | admin | Recovery administrator | Roles, scopes, assignments, policies and audit |

Select an identity in `/demo` or `/login`. This is an explicit simulator, not authentication. Registration and recovery demonstrate a challenge using the openly displayed code 246810. Do not enter a real password, OTP, payment PIN or identity document. The recovery administrator is intentionally protected from deactivation so a reviewer can recover the demo.

## Review script

1. Home → Stays → Nile Haven Lodge. Select Garden twin, one room, three nights from 12 October. Subtotal is USD360.00; complete demo checkout and inspect My bookings.
2. Events → Nile Breeze Music Festival. Two general admission tickets total UGX80,000. A group-of-four ticket consumes four admissions. The event date is fixed by the seeded occurrence.
3. Marketplace → Handwoven Ugandan Basket. Natural, quantity one: UGX45,000 plus UGX5,000 Kampala delivery = UGX50,000.
4. Demo controls → pending. Complete another checkout, observe reduced availability, then advance 20 minutes. The hold expires and capacity returns. A late success is rejected for reconciliation.
5. Try failure, sold-out and notification-failure. Failed payments do not reserve inventory; unavailable stock stops confirmation; notification failure does not lose a confirmed booking.
6. Provider → own listing → Edit → Save draft → Under review. Reviewer → Approved → Published. With combined publication enabled, an authorised publisher may publish directly from review. Self-approval is denied unless explicitly configured.
7. Administrator → People & roles. Clone a role, edit its permission grants and assign it. Organisation, region and category restrictions apply together to listing actions. Revocation takes effect at the next service check.
8. Administrator → Workflows & policies. Change refund percentage, then cancel an older booking: its original policy percentage still applies. Rollback creates a new policy version rather than erasing history.
9. Create a support request or provider application, switch to Support and resolve it.
10. Save destinations, create a seven-day itinerary, export it, then reload to confirm persistence.

## Architecture

- `app/page.tsx` and `app/[...slug]/page.tsx`: route entry points.
- `components/uganda/app.tsx`: shared public shell, discovery, detail, planning, checkout, account and demo screens.
- `components/uganda/admin.tsx`: administrative/provider workspaces, scoped role and policy controls.
- `components/uganda/access.tsx`: sample registration, sign-in/recovery and provider application.
- `lib/uganda/model.ts`: typed domain entities and integer money formatting.
- `lib/uganda/seed.ts`: one coherent deterministic dataset.
- `lib/uganda/service.ts`: central state transitions, permissions, stock, checkout, workflow and policies. UI actions call this service; denied actions throw without committing the cloned state.
- `lib/uganda/adapters.ts`: typed contracts for future trusted payment, inventory, identity, notification, catalogue, GIS and planner services.
- `components/ui`: starter-provided shadcn primitives reused for buttons, inputs, tabs, dialogs, sheets, switches, tables and notifications.
- `app/globals.css`: visual tokens, component styling and responsive rules.
- `tests/run.mjs`: deterministic service-level journey checks using Node assertions.

## Transaction rules in this demo

USD is stored in cents; UGX is stored in whole shillings. No floating-point business totals or silent currency conversion are used. Mixed-currency carts are rejected. Delivery is charged once per product-containing order. Sample taxes are included and no extra tax is calculated. Same-currency mixed carts confirm atomically within one synchronous browser store; real provider suborders and distributed transactions are not implemented.

Prices and refund policy are snapshotted on booking. Retry with the same checkout key returns the same result. Pending holds expire against the demo clock. Inventory is conservatively pooled across dates and variants; it is not a daily room or departure ledger. Date amendments keep the same rate and quantity. Production seasonal repricing, nightly availability, party eligibility and permit issuance require server implementation.

A cancellation records an immediate simulated percentage refund and releases an unfulfilled reservation. It is not evidence of disbursement. Separate approval, payout reconciliation, line-level partial refunds and return inspection are production requirements, recorded as gaps in the coverage register. Confirmed vouchers download as clearly marked text and are not valid for travel or entry; QR signing/scanning is not implemented.

## Governance and decision register

Implementation decisions: reusable domain/services; exact monetary representation; permission-based actions; persistent identifiers; explicit states; simulator isolation. These are concrete implementation choices.

Deployment configuration: review/publication mode, self-approval rule, refund percentage, hold duration and transaction enablement. The UI validates supported values, versions changes, retains history and supports rollback. Turning payments off blocks checkout while browsing remains available.

Operational assignments: named account, active role, organisation and optional region/category scope. These are assigned after the capability exists. The sample org-1 through org-5 references represent the five fictional provider organisations; they confer no legal authority.

The prototype does not ask stakeholders to resolve assignments as missing functional requirements. Production readiness still requires verified external service arrangements, secure initial provisioning, event-specific scope, independent configuration approval where applicable, escalation and approved policy bounds.

## Accessibility and responsive behaviour

Public content reflows at 1150, 850 and 560 CSS pixels. Four-column collections become two and then one column; details and booking panels stack; admin navigation becomes a horizontal strip and wide data tables retain internal scrolling. Dialogs, sheets and tabs use accessible primitives. Forms have labels, status messages use the notification region, focus is visible, reduced motion is respected and a skip link is provided.

This release is not a WCAG conformance certification. Body and operational metadata use 16px and 12px baselines; compact brand lettering is a decorative exception. Review final brand typography before production. Screen-reader testing, browser/device coverage and independent contrast audit remain required. Browser QA evidence is recorded in `TEST_REPORT.md`.

## Design system

Forest green #006B3F and deep green #003D2B carry brand identity and primary actions. Yellow #FCDC04 supplies highlights and discovery calls to action. Red #D90000 appears in accents and destructive/error states. Target distribution among coloured elements is approximately 50/30/20; it is not an audited pixel-area ratio. Most reading surfaces are neutral white, warm off-white or pale green. Red is not indiscriminately used for ordinary confirmation.

Typography uses a system sans-serif with occasional Georgia display emphasis. Container width is capped at 1240px. Spacing uses 8–12px control gaps, 18–28px card padding and 40–65px section spacing. Corners are generally 7–12px. Cards are semantic articles with independent save controls. Brand favicon is an original geometric mountain/sun motif, not an official government emblem.

## Integration and production boundaries

Replace browser authority with authenticated server sessions and verified organisation context. Enforce permissions in APIs, files, background jobs and database queries. Add optimistic concurrency, transaction isolation, audit integrity, backup/restore and data retention. The local store is intentionally editable and must never hold real sensitive data.

Payments require signed callbacks, amount/merchant verification, independent payment-attempt records, idempotent financial postings, reconciliation and refund state machines. Notification delivery belongs in a server queue. AI must use approved sources and availability services, with evaluation and authorization at every tool boundary. The current assistant is deterministic text matching and clearly labelled as simulated.

Google Maps replaces the schematic map. Configure the runtime browser key and map ID as described in google-maps.md. Without them, searchable listings and manual coordinate forms remain available. Legacy destination coordinates are approximate and do not enable directions. Road routing and travel-time calculation remain a separate integration.

Native iOS/Android, offline synchronization, biometric activation, ticket scanning, multilingual English/French/Swahili coverage, live weather, media upload/moderation, settlements and production security/privacy controls remain outside this working prototype. They are not represented as completed merely because a page exists.

## Images and rights

See `image-sources.json` for exact source and image URLs. Photography is used as illustrative reference material in this private design prototype. Obtain suitable rights or replace assets before public release. The large original hero image should be replaced with licensed, optimised responsive renditions before performance acceptance testing. Images of actual properties/craftwork do not represent the fictional providers. Destination images beyond the directly sourced places are labelled as inspiration, not documentary coverage of every location.

## WebMCP

The client feature-detects `document.modelContext` and registers a catalogue search and saved-place toggle using the same state/actions as the UI. Both tools validate arguments and are cleaned up on unmount. The available QA browser did not expose modelContext, so runtime WebMCP validation was unavailable; these optional integrations are not claimed as verified.

## Visual refresh

The illustrated full and compact footers, newsletter, catalogue covers, card photography, date badges and booking styles have been revised against the mockups. See VISUAL_REVIEW.md for findings and validation, and IMAGE_CREDITS.md for added assets. The source package includes updated design tokens and all visual assets.
