A production-grade bilingual commerce and logistics website that turns a regional distributor's catalogue, branch network, and procurement services into a fast, discoverable, and conversion-focused digital experience.
Sole Developer & Technical Architect Timeline: June–August 2026
Built a bilingual commerce and logistics platform for a regional distributor.
11
client-side routes
The SPA supports direct navigation across company, catalogue, news, contact, and legal surfaces.
7
mapped locations
The logistics map visualizes the operational network and regional movement of goods.
2
supported languages
English and Somali content share one React Context translation system with local persistence.
01 / Project evidence
Project visual and links
Original illustration
Samaale website concept illustration
A custom visual representation of the site’s commerce and logistics experience; this is not a browser screenshot.
02 / System design
Architecture diagram
The platform separates the customer-facing React application from the contact trust boundary: static assets and prerendered routes are delivered at the edge, while the only server-side workflow validates and protects inquiry submissions before sending them through Resend.
01
Product discovery → buyer inquiry
The public catalogue stays in the customer-facing app; the final inquiry can hand off to WhatsApp.
STEP 01
Browser
Buyer
Arrives at a prerendered company or product route.
HTTPS route
STEP 02
React 19 · React Router 7
Company site
Renders the English/Somali experience and route-level content.
Search / filter state
STEP 03
Typed product data
Catalogue
Search and category filters narrow the 27+ product entries.
Product detail
STEP 04
Portal modal
Product view
Shows the selected product details without leaving the catalogue.
User handoff
STEP 05
WhatsApp link
Inquiry handoff
Carries the buyer to the company’s inquiry channel.
02
Protected contact submission
The browser collects the request, but email delivery and abuse controls stay behind the Cloudflare Worker boundary.
STEP 01
React client
Contact form
Collects the message and obtains a Turnstile response.
HTTPS + token
STEP 02
Cloudflare Turnstile
Bot verification
The Worker verifies the challenge token server-side.
Browser → server trust boundary
Validated payload
STEP 03
Cloudflare Worker
Request checks
Checks body size, JSON shape, required fields, types, and limits.
Rate-limit check
STEP 04
SHA-256 identity + KV
Abuse limit
Applies a short-lived request limit before an email is sent.
Email API
STEP 05
Resend
Delivery
Sends the validated inquiry using server-side credentials.
External email provider
03
Build and deployment path
Static routes and the contact API have separate deployment responsibilities.
STEP 01
React + TypeScript + Vite
Source app
Builds route chunks and shared vendor bundles.
TypeScript build
STEP 02
Prerender + Vercel
Public pages
Serves static route output and browser assets through the edge.
Prerendered output
STEP 03
Cloudflare Worker
Contact API
Handles the protected inquiry path independently of the static app.
Separate server-side boundary
Edge delivery
STEP 04
KV + Turnstile + Resend
Supporting services
Provide rate limiting, challenge verification, and email delivery.
Arrows show the main request or data handoff. Boundary labels mark local-only processing, browser-to-server transitions, or external services.
03 / Engineering decisions
Choices and trade-offs
Decision 01
Keep catalogue data in the public app
Choice: Use typed product content and client-side filtering for a mostly read-oriented catalogue.
Trade-off: Fast, simple browsing avoids a product API, while catalogue updates still require a content/build release.
Decision 02
Isolate the contact trust boundary
Choice: Send inquiries through a Cloudflare Worker instead of exposing email provider credentials in the browser.
Trade-off: The request path gains bot checks and rate limiting, but delivery depends on Worker, KV, Turnstile, and email provider availability.
04 / Implementation notes
Architecture, code, and techniques
Architecture and code organization
The codebase is organized around a single React application entry point and a component dependency tree that keeps business sections independent while sharing infrastructure utilities. App.tsx owns global concerns such as routing, page loading, error recovery, floating actions, and route-change analytics. Feature components then own their local data and interaction state: Hero manages the timed media and typing state machine, ProductCatalog manages search and filtering, NewsArticleModal manages article galleries and sharing, and LogisticsMap owns the Leaflet view. This boundary keeps the main composition readable and lets individual sections be lazy-loaded or audited in isolation.
Typed data models make products, news, branches, partners, testimonials, and translations predictable to render and safer to refactor.
ReactDOM.createPortal keeps catalogue and article dialogs above layout constraints while preserving a clean parent component tree.
A CustomEvent channel connects the header brand menu to the catalogue without prop drilling across unrelated sections.
ErrorBoundary, LazyRender, ScrollReveal, RouteChangeTracker, and the focus-trap hook provide reusable cross-cutting behavior instead of one-off page logic.
Customer-facing techniques
The experience was designed around progressive disclosure. The homepage establishes trust with company history, product categories, service cards, partner logos, testimonials, and regional reach; deeper content is available through modals and direct routes when a visitor is ready to explore. The product catalogue uses useMemo-backed search and filtering, loading skeletons, aspect-ratio media, and a product detail modal. Product inquiries can then move directly into WhatsApp, reducing the distance between discovery and a real commercial conversation.
The header changes height, contrast, and shadow after scrolling, while the mobile drawer uses a spring animation and trapped keyboard focus.
The hero combines a nine-item media slideshow, AnimatePresence crossfades, a Ken Burns effect, and a locale-aware typing animation.
News articles are deep-linkable, support image galleries and Web Share API handoff, and migrate legacy hash URLs to path-based URLs.
The logistics section pairs service descriptions with a Leaflet map, seven custom location nodes, and animated route polylines to make regional capability concrete.
Performance, SEO, and accessibility
Performance was treated as an architectural concern, not a final polish step. React.lazy and Suspense split page-level code, LazyRender defers below-the-fold work with IntersectionObserver, and Vite manualChunks separates React, Motion, Leaflet, and icons for cache-friendly delivery. The post-build pipeline prerenders route HTML, optimizes media with Sharp, and generates sitemap and feed assets. Dynamic head management supplies route-specific titles, descriptions, canonical URLs, Open Graph data, and a large social preview.
The reduced-motion system combines MotionConfig reducedMotion="user" with component-level useReducedMotion checks.
Semantic landmarks, skip-to-content navigation, descriptive image alt text, ARIA menu/dialog states, Escape-key handling, and focus restoration support keyboard and assistive-technology users.
Playwright and axe-core are part of the documented verification workflow, so accessibility can be checked against the shipped interface rather than assumed from the source.
Secure contact and deployment design
The contact form is the deliberate trust boundary in the system. The browser performs immediate UX validation, but the Cloudflare Worker treats every request as untrusted: it verifies environment configuration, rejects oversized bodies, parses JSON, validates six fields with type, length, and pattern constraints, verifies the Turnstile token with Cloudflare, hashes the request identity with SHA-256 for a short-lived KV limit, and only then sends an HTML notification through Resend. This keeps provider credentials and abuse controls server-side while preserving a simple form experience for visitors.
The frontend is delivered as a static SPA through Vercel and its edge CDN, while the API runs in the Cloudflare Workers isolate runtime.
Vercel build and deployment, Cloudflare Pages Functions, Resend, Turnstile, KV, Leaflet tiles, and GA4 are connected through explicit environment boundaries.
The deployment model supports HTTPS, edge caching, Brotli compression, route rewrites, prerendered HTML, and server-only secrets without adding a traditional application server.
Evidence
Evidence snapshot
Public technical case-study snapshot based on the implementation documentation. Credentials, private customer data, and provider secrets are intentionally excluded.
Source footprint30+ TS / TSX filesDOCUMENTED
UI surface22 React componentsDOCUMENTED
Catalogue27+ productsIMPLEMENTED
LanguagesEnglish + SomaliIMPLEMENTED
Contact protectionTurnstile + KV limitIMPLEMENTED
SYSTEM: bilingual commerce and logistics SPA
DELIVERY: Vercel edge + Cloudflare Worker API
CONTROL: typed validation, bot verification, rate limiting
OUTPUT: catalogue, map, news, SEO, and inquiry workflows
Counts describe the published catalogue and implementation structure. No conversion-rate or performance improvement is claimed without analytics or a measured before/after baseline.
05 / Verification
Verification methodology
01
Translate the business model into information architecture
Grouped the company around the decisions a buyer actually needs to make: what Samaale supplies, where it operates, which logistics services it provides, and how to start an inquiry.
02
Build reusable interaction primitives
Used typed data arrays, shared components, portals, Motion transitions, and event-based coordination so catalogue, news, navigation, and location experiences could evolve without duplicating stateful UI logic.
03
Protect the only server-side boundary
Kept email credentials and abuse controls out of the browser. The Worker checks configuration, body size, JSON shape, field types and limits, Turnstile, then a SHA-256-derived KV rate limit before calling Resend.
04
Verify delivery, accessibility, and discoverability
Combined strict TypeScript checks, production bundling, prerendering, route metadata, sitemap and feed generation, Playwright/axe accessibility auditing, reduced-motion handling, semantic HTML, and keyboard focus management.
06 / Ownership
What I personally contributed
This section separates my direct contribution from broader project outcomes.
Owned the information architecture, visual system, frontend implementation, deployment model, and technical documentation.
Designed the catalogue and news systems with typed content models, category filtering, search, portals, detail views, and shareable URL states.
Built the logistics story as both service content and an interactive Leaflet map with custom location nodes and animated route polylines.
Created the Cloudflare Worker contact pipeline, including validation, Turnstile verification, SHA-256 rate limiting, Resend email templates, and safe environment-variable handling.
