Getting Started Guide

Prerequisites

PHP ≥ 8.2 runtime (composer requires ^8.5; CI runs on 8.2 — see note below), Composer 2

MySQL 8 (or SQLite for quick local runs) and Redis (optional locally; predis is pure-PHP so no ext-redis needed)

Node.js + npm (Vite asset build for the backend package)

Python or PHP CLI to serve the static frontend

Version note: composer.json declares "php": "^8.5" while CI installs PHP 8.2 and the Docker backend image is php:8.5-fpm-alpine. For local dev, match your environment to whichever target you deploy to.

Section sources: composer.json, ci.yml, Dockerfile

Backend Setup

Base API URL: http://127.0.0.1:8000/api

Interactive OpenAPI docs (Scramble): http://127.0.0.1:8000/docs/api

Section sources: README.md

Frontend Setup

Landing page: http://localhost:8080/index.html

Admin suite: http://localhost:8080/admin/index.html

The shared core resolves its API base in js/common.js: window.TP_CONFIG.apiBase overrides, otherwise it defaults to http://127.0.0.1:8000/api. If you serve the API on another port, set TP_CONFIG before common.js loads.

Section sources: README.md, common.js

Default Credentials

Role	Email	Password
Admin	`admin@threedos.com`	`password`

Additional seeded users exist via User5Seeder; roles are provisioned by RoleAndPermissionSeeder (super_admin, admin, user, agency).

Section sources: README.md, database/seeders

Environment Variables That Matter

Variable group	Keys	Purpose
Auth	`JWT_SECRET`	tymon/jwt-auth token signing
Payments	`PAYMOB_PUBLIC_KEY`, `PAYMOB_SECRET_KEY`, `PAYMOB_HMAC`, `PAYMOB_INTEGRATION_IDS`	Hosted checkout + webhook HMAC verification
AI	`GROQ_API_KEY`, `GROQ_MODEL` (default `llama-3.1-8b-instant`)	Groq LLM calls (config/services.php#L59-L62)
Social login	Google/Facebook client IDs + secrets	Socialite redirect flow
Mail / queue / cache	standard Laravel keys	Notifications, report jobs, Redis cache

Section sources: .env.example, services config

Running The Test Suite

CI mirrors this: Pint style check then full PHPUnit run on ubuntu-latest with PHP 8.2 (ci.yml).

Section sources: README.md, ci.yml

One-Command Alternatives

composer setup — install, copy env, generate keys, storage link, sqlite touch, npm build (composer.json scripts)

composer dev — concurrent artisan serve + queue:listen + Pail logs + Vite dev server

php artisan seed:fresh / sync:fixtures / sync:cities — custom console commands for reseeding and fixture sync (Console/Commands)

Troubleshooting Quick Hits

401 everywhere after reseed — old JWTs signed with previous JWT_SECRET; log in again.

Webhook rejected — PAYMOB_HMAC mismatch or route not excluded from CSRF (paymob/webhook).

Weather 429s — throttle:weather limiter; responses are Redis-cached, check CACHE_DRIVER=redis.

Reports empty PDF — queue worker must run (queue:listen) since generation is a queued job.

Getting Started Guide

Table of Contents#

Prerequisites#

Backend Setup#

Frontend Setup#

Default Credentials#

Environment Variables That Matter#

Running The Test Suite#

One-Command Alternatives#

Troubleshooting Quick Hits#

Table of Contents