DIREKT Visual Completion and AI-Native Upgrade Plan

Programme: VC — DIREKT Visual Completion and AI-Native Product Upgrade
Governing issue: #259
Programme stages: VC0 preparation, then VC1–VC8 implementation
Primary surfaces: Android, customer/provider web/PWA, internal operations portal
Parent direction: docs/product/WORLD_CLASS_PRODUCT_AND_AI_PLAN.md
AI architecture: docs/architecture/AI_PRODUCT_ARCHITECTURE.md

Completion checkpoint — 2026-07-21

The owner-approved execution hybrid — Structured Trust for proof/information architecture, Neighbourhood Marketplace for customer warmth/imagery and Field Utility for provider/operations density — has been implemented through the VC1–VC8 programme without replacing canonical backend/business authority.

Promotion history and candidate evidence:

  • VC1–VC6 implementation was promoted through PR #268 at c5eb25b2e579d7f148b67130baf307a45f11e7a0;
  • the provider-neutral AI foundation was promoted through PR #265;
  • VC7 implements bounded customer discovery assistance, grounded public Help, provider onboarding/readiness guidance and provider profile drafting with source-controlled governance, evaluations, fail-closed switches and deterministic/manual fallback;
  • restricted evidence/OCR/operations AI remains disabled pending the separate approvals required by this plan;
  • VC8 permanent quality/visual-evidence ownership is integrated into the normal functional-PWA and Android CI lanes;
  • candidate source 2bb734660b520940311c4d2b9c088d8f15224755 passed every permanent applicable regression gate;
  • web/operations evidence: run 29829438711, artifact ID 8494672572, digest sha256:212607749a2c3525e15cb46083f06c221ca0b485b0987f5ae338d5d2bf8de3b0;
  • native Android evidence: run 29829437845, artifact ID 8494745779, digest sha256:ce86f3affd2c8b3b797e8a22de1dda2fd080d32f3a46b20d365500ae08a1a0bb;
  • native Customer Discover, Provider Overview and Provider Evidence captures were visually inspected and confirmed synthetic-only and free of private evidence/raw coordinates/developer-harness leakage;
  • the redundant standalone VC8 screenshot workflow is removed at final closure because permanent PWA/Android evidence lanes now own the requirement.

This checkpoint records VC1–VC8 implementation completion evidence, subject to final closure-head regression and PR #270 promotion. It does not authorize real Phase 11 participant/evidence execution, restricted-data AI, real communications, real money or Phase 12 production release. The non-negotiable rules and all stage requirements below remain authoritative for maintenance/regression.

1. Objective

Transform the already functional DIREKT system into a visually world-class, AI-assisted, trustworthy local-services marketplace without rebuilding or weakening the existing backend, data, security, trust, privacy, integration or release architecture.

The programme must close the current imbalance:

  • backend/domain/trust architecture is comparatively mature;
  • customer/provider/operations UI is still visually prototype-like in important areas;
  • global-marketplace-level imagery, hierarchy, interaction polish and conversion simplicity are incomplete;
  • AI is not yet a first-class product capability across the major journeys.

VC1–VC8 therefore modernizes the presentation and intelligence layers while preserving canonical business authority.

2. Benchmark target

Use a composite benchmark:

  • Urban Company — marketplace polish, provider professionalism and operational quality;
  • Checkatrade — visible trust/rechecks and consumer trust language;
  • Taskrabbit — short path from need to provider/action;
  • Thumbtack — AI-guided natural-language/multimodal discovery;
  • DIREKT — stronger check-specific proof, privacy-by-precision, Zambia resilience and human-accountable trust.

Do not copy any one product literally.

3. Non-negotiable rules

Every VC stage preserves:

  1. proof before persuasion;
  2. no blanket Verified badge;
  3. check-specific state, scope, dates/currentness, meaning and limitations;
  4. icon + text + colour for state, never colour alone;
  5. map plus accessible list equivalent;
  6. privacy by precision;
  7. public work/premises imagery separate from private evidence;
  8. payment/commercial state separate from trust authority;
  9. Android remains the primary Version 1 native client;
  10. PWA remains additive and uses canonical API/BFF boundaries;
  11. operations remains privileged and separated from public clients;
  12. AI may assist but cannot become authorization, trust, payment or legal authority;
  13. manual/non-AI paths remain available for core tasks;
  14. gated integrations are represented truthfully;
  15. low-bandwidth/offline/retry are first-class;
  16. no real participant/evidence/payment/production activation without existing gates.

4. Repository control and regression rule

Before material VC implementation:

  1. fetch current stable main and current implementation-lane state;
  2. verify predecessor CI and managed evidence;
  3. resolve the known historical W7/W8 verifier-to-lock coupling so the next legitimate lane owner does not invalidate historical closure;
  4. formally claim the implementation lane for exact bounded paths;
  5. implement in small vertical slices;
  6. run exact-head platform and regression gates;
  7. record synthetic-safe visual evidence;
  8. merge only after review and green gates;
  9. synchronize branches and update status/lock/handoff.

Do not create a parallel replacement application.

5. Current visible gap summary

Cross-product

  • inconsistent typography hierarchy;
  • primitive/placeholder iconography in places;
  • insufficient marketplace imagery;
  • text-heavy forms/cards;
  • developer/workstream/API terminology leaking into visible UI;
  • incomplete shared loading/empty/error/offline visual patterns;
  • uneven responsive/adaptive polish;
  • trust semantics are strong but not yet presented beautifully;
  • AI is not yet embedded as a product assistance layer.

Customer

  • Discover/search feels functional rather than rich/local;
  • search suggestions and natural-language need description are weak/missing;
  • map/list experience is incomplete while Maps remains gated;
  • provider cards/profile need stronger imagery, hierarchy and trust explanation;
  • enquiry/review/complaint/account flows need final polish and simpler language.

Provider

  • workspace exposes implementation concepts in places;
  • onboarding/readiness needs guided task hierarchy;
  • raw category/location concepts must become user-safe controls;
  • verification/evidence upload/correction should feel calm and professional;
  • business/portfolio/services/enquiries/commercial states need coherent component families.

Operations

  • functional breadth exists but presentation is prototype/admin-test oriented;
  • queue → case → evidence → decision needs a desktop-grade review workspace;
  • development/test-state links and fixture language must not define production UX;
  • AI case summarization/checklist assistance is not yet implemented.

6. Design character

The approved design should combine, in a controlled hybrid if owner-approved:

Structured Trust

  • calm neutral surfaces;
  • precise information hierarchy;
  • restrained green semantic identity;
  • strongest check-specific trust presentation;
  • high accessibility and low-bandwidth suitability.

Neighbourhood Marketplace

  • human, local, warm;
  • Zambia-relevant provider/work/category imagery;
  • welcoming marketplace character;
  • stronger visual discovery without overpowering proof.

Field Utility

  • fast, task-oriented;
  • flatter efficient structures;
  • strong map/list and provider workspace patterns;
  • high-density operations composition.

No direction is silently selected. Owner approval is explicit.

7. AI visual interaction language

Create reusable patterns for:

  • “Describe what you need” natural-language entry;
  • optional approved photo/voice input;
  • AI suggestions with editable confirmation;
  • clarifying-question chips/cards;
  • “Why this result” explanations;
  • AI-generated summary labels;
  • source/trust facts displayed separately from AI synthesis;
  • uncertainty/fallback treatment;
  • operations copilot side panel/inline assist;
  • provider onboarding assistant;
  • evidence quality/extraction suggestions;
  • AI unavailable/manual fallback.

Do not use decorative sparkle/robot icons as a substitute for clear function. AI should feel embedded and useful, not theatrical.

VC0 — Preparation and control

VC0 establishes:

  • repository-wide visual audit;
  • screen-level gap matrix;
  • design directions;
  • benchmark target;
  • world-class product/AI plan;
  • AI architecture boundaries;
  • external design-tool workflow;
  • regression prerequisites;
  • owner review checkpoint.

No broad UI implementation belongs to VC0.

VC1 — World-class design-system reconciliation

Goal

Create one canonical visual and interaction foundation across Android, PWA and operations while allowing platform-native adaptation.

Deliverables

Foundations

  • semantic colour roles for light/dark;
  • typography hierarchy and fallback policy;
  • 4dp/spacing grid;
  • layout density rules;
  • radii/elevation;
  • approved icon family;
  • imagery/illustration policy;
  • motion/reduced-motion;
  • adaptive breakpoints/window classes;
  • 48dp-class touch targets;
  • 200% text scaling/reflow;
  • low-bandwidth image tiers;
  • offline/error/loading/skeleton patterns.

Components

  • app bars/navigation/bottom nav/side rail;
  • search/AI need entry/suggestions/filters;
  • category tiles;
  • provider cards/profile/gallery;
  • trust summary/check detail cards;
  • status chips/timelines;
  • map/list controls;
  • enquiry/consent/review/complaint components;
  • provider readiness/services/areas/availability/evidence components;
  • operations queue/case/evidence/decision/audit components;
  • AI suggestion/explanation/confirmation/fallback components.

Exit

  • tokens/components documented;
  • Android/web/operations mapping clear;
  • no domain/API behavior changed;
  • accessibility rules documented;
  • exact-head documentation/design-system checks green.

VC2 — High-fidelity benchmark review and explicit approval

Required flagship set

Render the same scope in at least three directions:

  1. Customer Discover/Home;
  2. AI-assisted service-need entry/search;
  3. search results + map/list;
  4. provider public profile + trust details;
  5. provider workspace/overview;
  6. provider verification/evidence status;
  7. operations verification queue/case/evidence review.

Variants

  • compact/mobile customer/provider;
  • desktop customer/provider web;
  • tablet/adaptive where composition changes;
  • desktop operations review;
  • compact operations triage/field sample;
  • representative loading/empty/error/offline states.

Approval record

Exactly one:

  • APPROVE DIRECTION A;
  • APPROVE DIRECTION B;
  • APPROVE DIRECTION C;
  • APPROVE HYBRID with exact borrowed elements;
  • REVISE with concrete changes.

Silence is not approval.

VC3 — Approved Design DNA and component foundation

Goal

Convert approved high-fidelity direction into implementation-ready source-controlled components.

Deliverables

  • approved Stitch project/screen references where used;
  • reconciled Design DNA/tokens;
  • Android Compose token/component implementation;
  • PWA/web token/component implementation;
  • operations token/component implementation;
  • approved vector icon set;
  • imagery asset pipeline and low-bandwidth variants;
  • visual regression reference set;
  • AI interaction components;
  • deliberate platform-difference record.

Generated design code must not redefine API/business logic.

VC4 — Customer world-class experience

Implement Android + PWA together where capabilities correspond.

VC4A — Entry, discovery and AI-assisted need understanding

  • splash/session restoration polish;
  • onboarding/account/mode selection;
  • Discover/Home;
  • search and area control;
  • category discovery;
  • natural-language “describe what you need” entry;
  • clarifying questions;
  • deterministic/manual category fallback;
  • search suggestions/query expansion;
  • low-bandwidth/offline state.

VC4B — Results, map/list and provider decision

  • filters;
  • results list;
  • map/list equivalent;
  • provider cards;
  • comparison;
  • provider profile/gallery;
  • service/coverage/availability;
  • check-specific trust summary/details;
  • “why this result” explanation where AI ranking is active;
  • no-results/recovery.

Maps remains truthful to integration activation state.

VC4C — Conversion and accountability

  • saved providers;
  • structured enquiry;
  • contact-sharing consent/revoke/expiry;
  • enquiry detail/timeline;
  • reviews;
  • reporting/complaints;
  • help/support;
  • notification centre;
  • account/security/privacy.

Customer gate

  • public-safe data only;
  • no client-selected provider scope;
  • no private evidence/private exact coordinates;
  • AI output separated from canonical trust facts;
  • manual path works without AI;
  • accessibility/responsive/offline tests pass;
  • exact-head Android/PWA/backend/OpenAPI tests pass where touched.

VC5 — Provider professional workspace

VC5A — Onboarding, business identity and readiness

  • provider pathway;
  • representative/business details;
  • service/category selection;
  • operating model;
  • service areas/public premises controls;
  • portfolio/public imagery;
  • readiness/next actions;
  • publication status.

AI may explain requirements, draft profile copy and help category selection; provider confirms public content.

VC5B — Verification and evidence

  • requirement checklist;
  • evidence capture/file upload;
  • progress/resume/retry;
  • timeline;
  • action required/correction;
  • review/declaration;
  • expiry/renewal.

AI/OCR may identify quality issues or extract candidate fields only after the use case passes restricted-data governance. It never approves a check.

VC5C — Work and business management

  • availability;
  • enquiries/detail/response;
  • contact handoff;
  • reviews/provider response/appeal;
  • subscription/invoice/receipt states;
  • provider insights where data supports them;
  • account/security/support.

Real payments remain separately gated.

VC6 — Operations mission control

VC6A — Verification core

  • mission-control dashboard;
  • queue/filter/SLA/ownership;
  • case detail;
  • secure evidence viewer;
  • checklist;
  • reason/decision controls;
  • provider operations summary;
  • publication eligibility;
  • audit history.

VC6B — Trust and field operations

  • field assignments/visit records;
  • escalations/overrides;
  • complaints;
  • incidents;
  • review moderation/appeals;
  • interaction history;
  • expiry/remediation.

VC6C — Commercial/reporting/configuration

  • subscription exceptions;
  • reconciliation shell within active payment gates;
  • operational reporting;
  • taxonomy/evidence rules where authorized;
  • audit explorer;
  • roles where authorized;
  • system health/queues.

Adaptive rule

  • desktop: queue + case + evidence/decision workspace;
  • tablet: one/two pane by task;
  • compact: task-focused triage/field flow, never a squeezed desktop table.

VC7 — AI intelligence layer

Activate only bounded, evaluated features with manual fallback.

VC7A — Public-safe AI

  • documentation-grounded support assistant;
  • natural-language discovery intent;
  • query/category expansion;
  • public provider comparison summaries;
  • plain-language trust explanation.

VC7B — Provider AI

  • onboarding copilot;
  • profile/service description drafting;
  • requirement explanation;
  • evidence-quality guidance.

VC7C — Restricted operations AI

Only after dedicated privacy/security/data-processing approval:

  • evidence OCR/extraction assistance;
  • case summarization;
  • missing-checklist highlighting;
  • draft action-required explanations;
  • complaint/review summarization;
  • moderation assistance;
  • risk/anomaly signals.

VC7 controls

Every AI use case requires:

  • use-case registry;
  • data classification;
  • model/provider abstraction;
  • prompt/version control;
  • structured validation;
  • authorization checks;
  • evaluation set;
  • prompt-injection/security tests;
  • cost/latency limits;
  • observability;
  • kill switch;
  • user disclosure/confirmation where material.

VC8 — World-class product, AI and quality gate

Visual

  • matches approved reference/Design DNA;
  • no primitive glyph/navigation placeholders;
  • no workstream/API/developer labels in production-facing UI;
  • imagery and typography are coherent;
  • responsive/adaptive layouts are intentional;
  • dark/light states complete where required.

Accessibility

  • TalkBack/screen reader;
  • keyboard/focus;
  • 48dp-class targets;
  • 200% scaling/reflow;
  • contrast;
  • reduced motion;
  • non-colour status;
  • accessible map/list equivalent;
  • form error focus/summary.

Product/trust/privacy

  • no blanket verification;
  • check scope/date/limitations preserved;
  • commercial state separated from trust;
  • no private evidence/location/contact leakage;
  • gated integrations not overclaimed;
  • no real participant/payment/production activation through VC alone.

AI quality/safety

  • grounding/accuracy thresholds;
  • hallucination/material-error thresholds;
  • manual fallback;
  • prompt-injection resistance;
  • sensitive-data disclosure tests;
  • tool/function authorization;
  • no excessive agency;
  • bias/fairness slices where applicable;
  • model outage fallback;
  • cost/rate/latency controls;
  • kill-switch exercise;
  • human approval for consequential decisions.

Regression

Run all applicable exact-head gates:

  • Android unit/lint/assembly/UI;
  • backend authorization/tests/build/migrations;
  • OpenAPI generation/drift;
  • database migration checks;
  • PWA typecheck/contracts/build/offline/security/responsive/accessibility;
  • operations tests/build/permission/accessibility;
  • AI evaluation/security suites;
  • documentation quality;
  • supply-chain/security.

Visual evidence

Use synthetic/public-safe data and record:

  • approved reference;
  • viewport/window class;
  • screenshots/visual comparisons;
  • loading/empty/error/offline states;
  • accessibility state;
  • AI state/fallback where relevant;
  • deliberate platform adaptations.

8. External design tooling

Google Stitch

Primary role:

  • generate 2–3 high-fidelity directions;
  • flagship mobile/desktop/adaptive screens;
  • Design DNA exploration;
  • approved design extraction through MCP where available.

Never adopt generated full-stack logic as canonical.

Suggested projects:

  • DIREKT-VC-A-Structured-Trust;
  • DIREKT-VC-B-Neighbourhood-Marketplace;
  • DIREKT-VC-C-Field-Utility;
  • after approval: DIREKT-VC-APPROVED.

Higgsfield

Secondary role only:

  • category concepts;
  • generic provider/work imagery concepts;
  • onboarding/empty-state illustration concepts;
  • moodboards;
  • store/promotional assets.

Never send private evidence, participant identity documents, raw contacts, private coordinates, restricted operations screenshots or secrets.

Generated assets require Zambia relevance, rights/provenance, accessibility, bias/stereotype and low-bandwidth review.

9. Implementation sequence

VC0 control/audit/benchmark
→ VC1 design system
→ VC2 high-fidelity owner approval
→ VC3 approved component foundation
→ VC4 customer experience
→ VC5 provider experience
→ VC6 operations mission control
→ VC7 AI intelligence layer
→ VC8 world-class quality gate
→ existing Phase 11 real pilot gates
→ existing Phase 12 production gates

Where safe, AI foundations may be prepared earlier, but user-visible AI activation follows the bounded VC7 governance/evaluation model unless a specific earlier slice explicitly includes and tests it.

10. Stop conditions

Stop rather than merge if a change would:

  • weaken backend authorization/IAM/BFF/session controls;
  • accept provider scope from client state;
  • expose private evidence or private exact location;
  • replace canonical state with fixtures while claiming functionality;
  • let payment improve trust/publication/ranking;
  • let AI make final consequential decisions;
  • send restricted data to an unapproved model/provider;
  • add unrestricted AI tools/agent access;
  • introduce real participant/evidence/payment/production behavior;
  • require unrelated framework rewrites;
  • regress predecessor gates;
  • contradict trust/privacy/accessibility rules.

11. Completion definition

VC1–VC8 is complete only when DIREKT no longer looks or behaves like a prototype in its primary customer, provider and operations journeys; AI is useful across high-value tasks without becoming an unsafe authority; visual quality is comparable to leading global service marketplaces; and every existing trust, privacy, security, integration and release regression gate remains intact.