Shopye: Building Trustworthy Local Commerce in Yemen
Shopye is Technway's digital business and commerce platform for Yemen. Its first product loop connects reliable Business information to Shopye Find, where people can discover relevant Businesses and take a genuine next action.
Selected requirements and acceptance criteriaSee the business rules and negative test scenarios behind Business identity, privacy-safe discovery, Arabic search and customer actions—on this page.Explore the evidence- My contribution
- Founder, product analysis, architecture and hands-on engineering
- First release
- Business foundation with an Arabic-first Taiz Find pilot
- Current evidence
- Implemented domain rules, web/API routes, tests and release criteria
How the parts fit together
Shopye Find is the first consumer-facing product, built on the same permanent Business foundation—not a second standalone project.
- Shopye Business
- Canonical identity, offerings, truthful geography, lifecycle and management
- Shopye Find
- Eligible local discovery, informed comparison, Business Profiles and actions
- Future commerce
- Optional Store and Marketplace, deliberately outside the first release
The problem worth solving
In Yemen, small Businesses operate through storefronts, home kitchens, social channels, delivery services and combinations of these. A conventional online Store is not the starting point for all of them. A social page also does not consistently tell a consumer what is available, where or how to act.
Shopye needed an underlying Business model that could describe these realities without inventing locations, ownership, reviews or available services. The first test of that model is whether someone in Taiz can find a real option, judge its relevance and use an accurate customer channel.
My role and the intended scope
I worked across product strategy, Business Analysis, domain modeling, frontend behavior and the engineering direction. That included defining the Business-to-Find loop, merchant onboarding, location and coverage rules, publication, source evidence, claims, consumer search, Reputation and proportional first-party measurement.
This is an ongoing Technway-owned product, not a client commission. Shopye's ambition extends across Yemen and includes further commerce products, but the current release boundary is intentionally narrow: a credible, Arabic-first Taiz Find pilot.
Platform decisions: making the Business model trustworthy
A polished search result is of little value if the underlying record is wrong. These choices determine which facts Shopye can safely preserve and present.
Keep the Business identity independent of its managers or future Store
What should remain intact when a merchant takes control of a sourced listing or changes how it sells?
- The trade-off
- Treating an account or Store as the Business would make a few early screens simpler but fragment customer trust, history and public URLs when ownership or products change.
- The decision
- Create one canonical Business entity. Merchant accounts manage it, Find presents it and an optional future Store can belong to it. Claims link verified management to the existing record rather than making another Business.
- What is implemented
- Business lifecycle, manager relationships and seeded-claim rules are implemented and covered by domain tests.
Supporting requirement:Preserving Business identity
Model real customer access without exposing private homes
How should a home-based seller be discoverable without a public shop address or a false promise of nationwide service?
- The trade-off
- One location field would simplify the schema, but it would incorrectly equate the Business base city, a visitable Location, Product delivery and Service Coverage.
- The decision
- Represent those separately. A home-based Business may have no public Location; its city and delivery or service coverage can still make it relevant to a customer without leaking an address.
- What is implemented
- Operating-model rules, Location relations, separate coverage structures and validation are represented in the code and domain contracts.
Supporting requirement:Privacy-safe customer access
Treat researched supply as a lead, not an endorsement
How can Shopye build a useful local catalog without publishing unconfirmed businesses or assigning ownership incorrectly?
- The trade-off
- Publishing everything found on social media would fill result pages quickly, but would introduce stale channels, duplicates and claims that no one actually verified.
- The decision
- Require provenance and operator review. Materialize a candidate only into an unclaimed Draft, keep a separate publication gate, and preserve the same canonical Business when a merchant later proves a claim.
- What is implemented
- Source-backed intake, duplicate detection and recheck, publication readiness and claim review are implemented. Actual Taiz supply is still subject to operator verification.
Supporting requirement:Source evidence and claims
Shopye Find: from local intent to useful action
Find is where the Business foundation meets a real consumer decision. The question is not simply whether a query matches. It is whether the option can serve this customer, what useful facts are known about it, and what the customer can do next.
The consumer journey
- Express a needArabic search or category
- Apply eligibilityPublic, available and serves the city
- Compare optionsUseful offerings and honest trust signals
- View a BusinessThe canonical public profile
- Take a real actionGenuine supported contact channel
Find supports Businesses, representative Products and Services—not a full Store catalog. A canonical Business Profile answers who the Business is, what it offers, where and how it serves customers, what genuine trust information exists and which contact actions are available.
Exclude ineligible results before ranking what remains
Should a popular Business appear in Aden if it can really serve customers only in Taiz?
- The trade-off
- Geography as a ranking hint would produce fuller-looking lists, but it could mislead users into choosing Businesses that cannot serve them.
- The decision
- Treat public lifecycle and customer access as hard gates. Only eligible Businesses, Products and Services enter result comparison; relevance and Reputation matter afterward.
- What is implemented
- Find eligibility, availability, geography and parent-Business visibility rules have code and deterministic test coverage.
Supporting requirement:Find eligibility and geography
Make Arabic search tolerant without making it opaque
How can users find the same service using different everyday Arabic words and spellings?
- The trade-off
- Pure exact matching misses common variants. Unrestricted AI rewrites could make suggestions difficult to explain and weaken geographic correctness.
- The decision
- Use bounded, deterministic normalization and controlled local-language synonyms, preserve city selection, and distinguish Businesses, Products and Services in result presentation.
- What is implemented
- The Find contract defines Arabic normalization, supported synonyms, query-intent grouping and constrained suggestions. The related search code and tests exist.
Supporting requirement:Arabic query handling
Measure actions without reporting imaginary sales
How do we tell whether discovery helps a Business before Shopye operates checkout or delivery?
- The trade-off
- Page views alone do not prove business value; an external WhatsApp or phone click also does not tell us whether a purchase followed.
- The decision
- Expose genuine Business contact channels and distinguish impressions, profile views and initiated customer actions. Do not call any of these a confirmed lead, order or sale.
- What is implemented
- Typed analytics and customer-action tests distinguish these event meanings. Verified public merchant outcomes are not yet available.
Supporting requirement:Honest action measurement
Example · Eligibility before ranking
Business rule: A result must be effectively public, available and able to serve the requested city before its text relevance or popularity is used to decide its position.
Negative scenario: An online Business that serves only Taiz cannot appear in Aden merely because its name matches, and a Hidden Business cannot appear through one of its Products.
Domain and Find rules have automated tests. Public Taiz supply, end-to-end Arabic/RTL behavior and merchant actions still need production-equivalent verification.
Reputation is intentionally separate from popularity and account claims: no fabricated zero-star average, no authoritative headline mean from one or two reviews, and no rating-based ranking boost before five published reviews. No confirmed customer purchases are claimed.
Selected requirements and acceptance criteria
These examples are drawn from the project's domain contracts and implemented rules. They demonstrate how I translate product decisions into verifiable behavior—including what must happen when something goes wrong. They are selected work samples, not the complete internal SRD.
Preserve one durable Business identity
Why it matters. A Business is a lasting commercial identity, not an account, storefront, public listing or current manager. Management and lifecycle changes should not erase its legitimate history.
Requirement. The same canonical Business shall retain its identity and relevant history through claim approval, manager changes, hiding, archiving and restoration. Restoring an archived Business must return it to Draft, not automatically publish it.
Acceptance scenarios
- Given an existing Business that changes manager, its canonical ID, URL, Products, Services and legitimate history remain attached to the same entity.
- Given an Archived Business, restoration returns it to Draft; public Find routes do not expose it until a separate permitted publication action succeeds.
Engineering evidence and limits: Canonical Business lifecycle rules and history-preserving claim flows exist in the codebase, with domain tests. End-to-end production recovery and publication remain release gates.
Separate where a Business is based from where it serves customers
Why it matters. Local commerce includes home-based sellers, physical shops, couriers, remote providers and hybrids. A base city, visitable Location and delivery or Service Coverage answer different questions.
Requirement. The canonical model shall separately represent privacy-safe base geography, real public visitable Locations, Product delivery reach, Service Coverage and remote-service availability, without exposing a home address as a public Location.
Acceptance scenarios
- Given a home-based Business, the public presence provides useful base city or coverage information without demanding or exposing its private home address.
- Given an online-only Business serving only Taiz, customer-access logic must not treat its internet presence as nationwide coverage.
Engineering evidence and limits: Separate domain tables and validation contracts cover operating model, public Location, Product delivery and Service Coverage. Public-data privacy checks remain a release condition.
Keep sourced research distinct from Business ownership
Why it matters. Yemen commerce depends heavily on public social channels. Research can help discover real Businesses, but observing a Facebook page does not establish who controls the Business or whether a particular claim is still current.
Requirement. Seeded Business candidates shall retain source evidence and receive an operator decision before materialization. Materialization creates an unclaimed Draft; public publication and merchant ownership are separate, explicitly authorized workflows.
Acceptance scenarios
- Given a candidate with unsupported fields, the system prevents review approval or canonical publication until the missing evidence is resolved.
- Given a possible identity duplicate, an operator must review that signal, and any new collision at materialization triggers recheck rather than creating a second Business.
Engineering evidence and limits: Seed intake, duplicate preflight/recheck and claim review flows are present with automated tests. The Taiz research cohort remains subject to real-world human review and explicit publication.
Exclude ineligible supply before ranking
Why it matters. A result should not be visible just because it matches a query. Public lifecycle and actual customer access determine whether a Business or offering belongs in consideration at all.
Requirement. Find shall apply server-authoritative lifecycle, parent-Business visibility, Product availability and requested-city access gates before ordering eligible Businesses, Products or Services.
Acceptance scenarios
- Given a Hidden or Archived Business, no associated offering appears in ordinary public Find results.
- Given a Published Product whose availability is unavailable, the Product is excluded from normal discovery.
Engineering evidence and limits: Find rules, input validation and deterministic tests exist. The production-equivalent Taiz customer journey must still be verified with reviewed public Businesses.
Make Arabic search useful without inventing matches
Why it matters. People can search for the same service using varied Arabic spellings and everyday Yemen-market terms. Query tolerance should improve recall while preserving actual location and offering truth.
Requirement. Search and suggestions shall normalize supported Arabic variants, respect query intent and selected-city scope, and return bounded deterministic suggestions drawn from eligible canonical supply.
Acceptance scenarios
- Given supported Alef, Yeh/Alef Maqsura, Teh Marbuta, diacritic or punctuation variants, equivalent search intent is handled consistently within the documented normalization rules.
- Given a selected city, an entity suggestion is excluded if its canonical access does not serve that city.
Engineering evidence and limits: Deterministic query normalization and suggestion logic are documented and tested at the rule layer. Native Arabic/RTL browser interaction requires release-level verification.
Measure customer actions without claiming sales
Why it matters. Shopye can help a consumer reach a merchant before it offers checkout or logistics. A genuine WhatsApp, phone or website action is useful evidence, but does not establish what happened afterward.
Requirement. Business Profiles shall expose only real supported customer channels, and analytics shall distinguish Find exposure, a deliberate profile view, and an initiated customer action without equating any of these with a completed transaction.
Acceptance scenarios
- Given a Business without a supported public contact channel, no fabricated call-to-action is rendered.
- Given a customer opening WhatsApp or a website, Shopye records an initiated action only; it does not record a confirmed purchase.
Engineering evidence and limits: Typed analytics events, customer-action rules and negative tests exist. Live merchant attribution, event quality and actual business outcomes are not yet verified.
Implementation, QA and current release status
Shopye uses Next.js and React for its web application, a NestJS modular-monolith API, and PostgreSQL with Drizzle for canonical Business and Offering data. It favors explicit domain and authorization boundaries over premature services and a separate search cluster.
Demonstrated in the repository
- Business, Offering, lifecycle and permission-oriented rules
- Seeded-source review, duplicate checks and claim workflows
- Find search, browse, Business Profile routes and typed analytics
- Domain tests and successful CI/Security workflows
Before a public Taiz release
- Human-reviewed and approved real Business supply
- Production-equivalent access control, privacy and Arabic UX QA
- Staging migrations, backup/restore and operational recovery
- Verified public search → profile → truthful customer action
Those release gates are still open. This work is evidence of product analysis and engineering, not proof of launched nationwide commerce, merchant adoption, completed transactions or WCAG conformance.
What this project has taught me
Good product decisions start with the right distinctions: a Business is not its account, its base city is not its public address, a source observation is not ownership proof, and a search result is not useful unless customers can genuinely act on it.
For Find, the consequence is especially concrete: relevance starts with truthful eligibility, not a ranking algorithm.The next important evidence is a real Taiz user journey backed by approved supply and recorded acceptance results.