Duka Platform

Architecture

Duka uses a monorepo structure managed by Turborepo. Each web application is an independent Next.js project deployed on Vercel. All apps share the same backend API and Firebase project.

duka-web/                  <span class="comment"># Turborepo monorepo</span>
├── apps/
│   ├── admin/             <span class="comment"># Next.js — admin panel</span>
│   ├── customer/          <span class="comment"># Next.js — customer app</span>
│   ├── seller/            <span class="comment"># Next.js — seller portal</span>
│   ├── delivery/          <span class="comment"># Next.js — delivery app</span>
│   └── docs/              <span class="comment"># Next.js — this docs site</span>
└── package.json           <span class="comment"># root workspace config

duka-api/                  # Laravel 11 REST API
├── Modules/
│   ├── Auth/
│   ├── Product/
│   ├── Order/
│   ├── Seller/
│   ├── Delivery/
│   └── Admin/
└── routes/api.php

Request flow

1. User authenticates with Firebase (email/password)
2. Client exchanges Firebase ID token for a Laravel Sanctum token via POST /api/auth/login
3. Subsequent requests use Authorization: Bearer <sanctum_token>
4. Role middleware (role:admin, role:seller, etc.) guards each route group

Tech Stack

Platforms

Customer App — apps/customer

• Sign in / Create account (Firebase + API)
• Home feed, categories, product search & browse
• Product detail, add to cart, checkout flow
• Order tracking with real-time status
• Profile, saved addresses, order history
• AI-powered chatbot (Gemini 2.0 Flash) at bottom-right

Seller Portal — apps/seller

• Multi-step KYC registration (Account → Shop Info → pending approval)
• Dashboard with sales analytics
• Product management (create, edit, variants, images)
• Order management (accept, fulfill, track)
• Shop settings & payout info

Delivery App — apps/delivery

• Multi-step agent registration (Account → Vehicle Info → pending approval)
• Available orders queue & accept/decline
• Active delivery tracking & status updates
• Earnings dashboard & history

Admin Panel — apps/admin

• Platform overview dashboard
• Seller KYC review & approval
• Delivery agent approval
• Product & category management
• Order monitoring
• User management (customers, sellers, agents)

API Reference

Base URL: https://api.duka.supplies/api (production) · http://localhost:8000/api (local)

Authentication

Products

Orders

Registration (KYC)

Authentication

All apps use Firebase Authentication (email/password) paired with Laravel Sanctum. Firebase handles credential storage and token generation. Laravel validates the Firebase ID token and returns its own Sanctum token for subsequent API calls.

Login flow

<span class="comment">// 1. Sign in with Firebase</span>
<span class="kw">const</span> cred = <span class="kw">await</span> signInWithEmailAndPassword(auth, email, password)
<span class="kw">const</span> idToken = <span class="kw">await</span> cred.user.getIdToken()

<span class="comment">// 2. Exchange for Sanctum token</span>
<span class="kw">const</span> res = <span class="kw">await</span> api.post(<span class="str">'/auth/login'</span>, { firebase_token: idToken })
<span class="kw">const</span> { token, user } = res.data

<span class="comment">// 3. Store and use for all API calls</span>
localStorage.setItem(<span class="str">'duka_admin_token'</span>, token)

Token storage keys

Firebase lazy initialization

All apps/*/lib/firebase.ts files use a Proxy pattern to defer Firebase initialization to client-side only. This prevents auth/invalid-api-key errors during Next.js server-side prerendering at build time.

<span class="comment">// lib/firebase.ts — lazy proxy pattern</span>
<span class="kw">let</span> _auth: Auth | undefined

<span class="kw">function</span> getInstance(): Auth {
  <span class="kw">if</span> (!_auth) {
    <span class="kw">const</span> app = getApps()[0] ?? initializeApp(firebaseConfig)
    _auth = getAuth(app)
  }
  <span class="kw">return</span> _auth
}

<span class="kw">export const</span> auth = <span class="kw">new</span> Proxy({} <span class="kw">as</span> Auth, {
  get(_, prop) {
    <span class="kw">const</span> a = getInstance()
    <span class="kw">const</span> val = Reflect.get(a, prop, a)
    <span class="kw">return typeof</span> val === <span class="str">'function'</span> ? val.bind(a) : val
  },
})

Environment Variables

Admin — apps/admin

Seller — apps/seller

Same Firebase variables as admin, plus:

Delivery — apps/delivery

Same Firebase + API variables as seller.

Customer — apps/customer

Same Firebase + API variables, plus the Gemini API key (server-side only):

Deployment

Vercel — frontend apps

Each app is deployed as a separate Vercel project pointing to the monorepo root:

1. Import github.com/abdulrazakmustafa/duka-web in Vercel
2. Set Root Directory to apps/admin (or customer, seller, delivery, docs)
3. Framework preset: Next.js
4. Add all environment variables for that app
5. Assign custom domain

Custom domains (Cloudflare DNS)

Laravel API — Hostinger

1. Upload duka-api/ to Hostinger via File Manager or Git
2. Run composer install --no-dev in the API directory
3. Set .env with database credentials, APP_KEY, Firebase service account path
4. Run php artisan migrate
5. Point api.duka.supplies A record to the Hostinger server IP
6. Configure document root to public/

Firebase Setup

1. Go to console.firebase.google.com
2. Create project duka-app (or use existing)
3. Enable Authentication → Email/Password sign-in method
4. Create a Web App and copy the config object:

   <span class="kw">const</span> firebaseConfig = {
     <span class="key">apiKey</span>:            <span class="str">"AIzaSy..."</span>,
     <span class="key">authDomain</span>:        <span class="str">"duka-app.firebaseapp.com"</span>,
     <span class="key">projectId</span>:         <span class="str">"duka-app"</span>,
     <span class="key">storageBucket</span>:     <span class="str">"duka-app.appspot.com"</span>,
     <span class="key">messagingSenderId</span>: <span class="str">"1234567890"</span>,
     <span class="key">appId</span>:             <span class="str">"1:123:web:abc123"</span>,
   }

5. Create a Service Account (Project Settings → Service Accounts → Generate new private key)
6. Upload the JSON key to Hostinger and set its path in Laravel's .env:FIREBASE_CREDENTIALS=/path/to/firebase-credentials.json

Email & SMTP

SMTP configuration (Hostinger)

<span class="comment"># Laravel .env</span>
<span class="key">MAIL_MAILER</span>=<span class="val">smtp</span>
<span class="key">MAIL_HOST</span>=<span class="val">smtp.hostinger.com</span>
<span class="key">MAIL_PORT</span>=<span class="val">465</span>
<span class="key">MAIL_ENCRYPTION</span>=<span class="val">ssl</span>
<span class="key">MAIL_USERNAME</span>=<span class="val">admin@duka.supplies</span>
<span class="key">MAIL_PASSWORD</span>=<span class="val">your_email_password</span>
<span class="key">MAIL_FROM_ADDRESS</span>=<span class="val">admin@duka.supplies</span>
<span class="key">MAIL_FROM_NAME</span>=<span class="val">"Duka"</span>

AI Chatbot

The customer app includes a Gemini 2.0 Flash powered chatbot. It answers questions about orders, delivery fees, how to sell on Duka, and general platform info.

How it works

1. Chat widget (components/ChatWidget.tsx) sends messages to POST /api/chat
2. Next.js API route (app/api/chat/route.ts) calls Gemini server-side
3. The API key (GEMINI_API_KEY) is never exposed to the browser

Limits

• Free tier: 1,500 requests/day, 15 requests/minute
• Context window: last 6 messages sent with each request
• Model: gemini-2.0-flash

<span class="comment"># Customer app .env.local</span>
<span class="key">GEMINI_API_KEY</span>=<span class="val">AIzaSy...your_key_here</span>

<span class="comment"># Also add GEMINI_API_KEY in Vercel dashboard</span>
<span class="comment"># for the duka-customer project (no NEXT_PUBLIC_ prefix)</span>

Roles & Flows

User roles

Seller KYC flow

1. Applicant registers a Firebase account & customer account via /auth/register
2. Submits shop info to /seller/register (requires role:customer token)
3. Seller record created with status: pending
4. Admin reviews in Admin Panel → approves → user role updated to seller
5. Applicant can now sign in to seller.duka.supplies

Delivery agent flow

1. Applicant registers a Firebase account & customer account
2. Submits vehicle info to /delivery/register
3. DeliveryBoy record created with status: pending
4. Admin approves → user role updated to delivery
5. Agent can now sign in to delivery.duka.supplies

Order lifecycle