# 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

```text
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.