Top.ug - Directory pro

---

• Live Demo: Directory Pro Demo
• Documentation: Directory Pro Docs
• Need help? Reach out via WhatsApp

---

A digital business cards directory - Built specicifically for Uganda — with mobile-money billing,an admin panel, and a built-in invoicing tool.

Demo Accounts

Check out the live demo at https://dirpro-demo.top.ug/ and sign in with one of the pre-seeded accounts:

Role	Email	Password	Access
Admin	admin@dirpro.demo	password	Full access, including the Admin panel (dashboard, card moderation, user management, settings)
User	user@dirpro.demo	password	Create and manage your own cards and invoices

These accounts are created by Database\Seeders\DemoSeeder, which is safe to run in production (idempotent, no Faker/factories).

Features

• Public directory — searchable, paginated grid of published business cards with avatars, bios, and social links. Each card has its own public page.
• Card management — authenticated users create and edit their own cards, including avatar uploads and social links (LinkedIn, WhatsApp, etc.). Cards are auto-published or queued for review depending on site settings.
• Billing (opt-in) — when billing is enabled, cards beyond the free slot require payment. Payments are collected via the ioTec Pay mobile-money API, with a wire:poll-driven payment-pending screen and a signed webhook that settles card and invoice payments.
• Invoices & receipts — users generate invoice/receipt documents against their own business card identity (the platform is never a party to user–client documents). Documents get auto-numbered, tax-calculated totals, tokenized public links, PDF downloads (dompdf), and an optional platform fee gate.
• Admin panel — dashboard, card moderation, user management (block/unblock with self-protection), invoice oversight, and a site-wide settings screen.
• Moderation & safety — admins and blocked-user middleware; blocked users' cards disappear from the public directory.

Tech Stack

• PHP 8.5 / Laravel 13
• Livewire 4 (single-file components) + Flux UI 2 (free + pro)
• Laravel Fortify for authentication (login, registration, 2FA, password reset)
• Tailwind CSS 4 with Vite
• ioTec Pay for mobile-money collection (OAuth token caching, webhook verification)
• dompdf for PDF generation
• Pest for testing

Getting Started

Prerequisites

• PHP 8.3+
• Composer
• Node.js and npm

Installation

composer run setup

The composer run setup script runs all of the above for you.

Development servers

composer run dev

This starts both the Laravel and Vite dev servers. Alternatively, run them separately:

php artisan serve
npm run dev

Configuration

All site behaviour is controlled from the Admin → Settings screen (a singleton settings row in the database), not via .env:

Setting	Purpose
auto_publish_cards	Publish new cards immediately instead of queuing for review
billing_enabled / free_slots_per_user / price_per_card	Card billing rules and price
currency	Platform currency (UGX / USD / ITX)
iotec_client_id, iotec_client_secret, iotec_wallet_id, iotec_callback_secret	ioTec Pay credentials (secrets stored encrypted)
invoices_billing_enabled / free_document_slots_per_user / price_per_document	Document platform-fee rules
default_tax_rate	Default tax applied to new documents
invoice_number_prefix / receipt_number_prefix	Document numbering prefixes

ioTec Pay testing

For local testing, use ioTec's sandbox MSISDNs to simulate Success, Failed, and Pending collection results. The webhook endpoint is:

POST /webhooks/iotec-pay

It is verified against the configured callback secret via the X-Iotec-Signature header. Payments are correlated to billables via externalId prefixes (card-{id} / invoice-{id}).

Project Structure

app/
  Enums/          CardStatus, PaymentStatus, Currency, DocumentType, DocumentStatus
  Models/         Card, Invoice, Setting, User
  Services/       IotecPayService, InvoicePdfService
  Http/Controllers/  Webhook + PDF download controllers
  Http/Middleware/   EnsureUserIsAdmin, EnsureUserIsNotBlocked
  Policies/       CardPolicy
routes/
  web.php         home + dashboard
  cards.php       card CRUD + payment-pending
  directory.php   public directory card pages
  invoices.php    invoice CRUD, public token views, PDF downloads
  admin.php       admin panel
  webhooks.php    ioTec Pay webhook
resources/views/pages/   Livewire single-file components

Testing

php artisan test --compact

The suite covers model/factory sanity, card CRUD, directory visibility, billing flow, free-slot limits, IotecPay service, admin access control, user moderation, and settings.

Lint & Static Analysis

composer run lint        # Laravel Pint (fixes formatting)
composer run types:check # PHPStan
composer run test        # lint + static analysis + full test suite