Kandura

Kandura is a custom apparel platform that brings together a Laravel operations portal, a versioned customer API, and a React customer experience. It supports the lifecycle of a garment design from customer profile and design management through order handling, invoicing, payments, wallet activity, notifications, and administration.

The repository contains the current release represented by the Kandura-16 line of development. The backend is built with Laravel 11 and PHP 8.2+, while the customer application is maintained as a separate React workspace in frontend/.

Product capabilities

Area	What the current implementation provides
Customer accounts	Registration, login/logout, protected profile management, address book, and customer-scoped permissions.
Design and ordering	Customer API resources for designs, orders, and reviews; the operations portal includes administration for designs and design options.
Payments and finance	Stripe dependency, customer wallets and transactions, invoice browsing, and signed invoice-download links.
Administration	A Laravel web portal for analytics, sales reporting, users, roles, permissions, orders, coupons, wallets, invoices, and notifications.
Notifications	In-app notification endpoints plus Firebase Cloud Messaging device-token registration.
Customer experience	A React customer workspace with a landing page, protected customer dashboard, and an administrator showcase route.

Architecture

Kandura separates the customer-facing application from the Laravel application while keeping business rules, authentication, persistence, and operational workflows in the backend. Customer API routes are versioned under /api/v1; authenticated customer routes use the customer guard and are controlled by resource-level permissions.

flowchart LR
    C[Customer] --> R[React customer app]
    A[Administrator] --> W[Laravel operations portal]
    R -->|HTTPS /api/v1| L[Laravel 11 application]
    W --> L
    L --> D[(MySQL)]
    L --> S[Object storage / S3]
    L --> P[Stripe]
    L --> N[Firebase Cloud Messaging]
    L --> I[Invoice PDF generation]

Loading

Component	Location	Responsibility
Laravel application	Repository root	Web portal, API, domain logic, access control, data migrations, and integration configuration.
Customer API	routes/api.php	Versioned endpoints for authentication, account, wallet, addresses, invoices, notifications, designs, orders, reviews, and device tokens.
Web portal	routes/web.php	Administrative and operational web workflows, including reports and management resources.
React customer app	frontend/	Customer-facing pages, local authentication state, API client, and Tailwind-based UI.
API request collection	storage/postman/	Bruno/Postman-style request collection for exercising the API.

For design and operational detail, consult the architecture guide and the API guide.

Prerequisites

Requirement	Recommended version	Purpose
PHP	8.2 or later	Laravel application runtime.
Composer	2.x	PHP dependency management.
Node.js	20 LTS or later	Asset compilation and React workspace.
npm	10.x or later	JavaScript dependency management.
MySQL	8.0 or later	Primary relational database.

The application may require credentials for services such as Stripe, Firebase Cloud Messaging, object storage, and outbound messaging depending on which workflows are enabled. Never commit real credentials, private keys, service-account JSON, or generated Passport keys.

Quick start

1. Configure the Laravel application

Clone the repository, install server and build dependencies, then create the local environment file.

git clone https://github.com/abedhamdi220/Kandura-Final-Project.git
cd Kandura-Final-Project
composer install
npm install
cp .env.example .env
php artisan key:generate

Configure DB_* in .env for a local MySQL database, then migrate and seed the baseline data.

php artisan migrate --seed

Run the Laravel application, queue worker, and Vite development server together:

composer run dev

Alternatively, use the processes separately when troubleshooting:

php artisan serve
php artisan queue:listen --tries=1
npm run dev

2. Configure the React customer application

The customer application is intentionally isolated in frontend/. Create its environment file from the template below and point it at the Laravel API.

cd frontend
npm install
cat > .env.local <<'EOF'
REACT_APP_API_URL=http://localhost:8000/api
REACT_APP_BACKEND_URL=http://localhost:8000
REACT_APP_GOOGLE_CLIENT_ID=replace-with-your-client-id
EOF
npm start

The development server normally listens on port 3000. Ensure its API URL ends in /api; requests are then routed to /api/v1/... by the application.

Environment configuration

The checked-in .env.example contains safe Laravel defaults. Complete it locally for the features you intend to run.

Variable group	Examples	Used for
Application	APP_NAME, APP_URL, APP_ENV, APP_KEY	Laravel application identity and encryption.
Database	DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD	MySQL connectivity.
Sessions, cache, queues	SESSION_DRIVER, CACHE_STORE, QUEUE_CONNECTION, REDIS_*	Stateful workloads, background jobs, and caching.
Mail	MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD	Delivery of application email.
Object storage	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET	Filesystem/S3-backed media workflows.
Firebase	FIREBASE_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS, FIREBASE_DATABASE_URL	Firebase integration and FCM credentials.
Messaging	ULTRAMSG_INSTANCE_ID, ULTRAMSG_TOKEN	UltraMsg service integration.
Passport	PASSPORT_PRIVATE_KEY, PASSPORT_PUBLIC_KEY	Explicit Passport key configuration when not using the default key files.
Customer app	REACT_APP_API_URL, REACT_APP_BACKEND_URL, REACT_APP_GOOGLE_CLIENT_ID	React API connectivity and Google sign-in client configuration.

Keep all secret values outside version control. Use a managed secret store for staging and production, grant least-privilege access, and rotate a secret immediately if it has been exposed.

Development workflow

Task	Command
Install backend dependencies	composer install
Install Laravel assets	npm install
Start Laravel, queue, and Vite	composer run dev
Build Laravel production assets	npm run build
Run the Laravel test suite	php artisan test
Format PHP code	./vendor/bin/pint
Install customer-app dependencies	cd frontend && npm install
Start customer app	cd frontend && npm start
Build customer app	cd frontend && npm run build
Run customer-app tests	cd frontend && npm test

Before opening a pull request, run the relevant tests and production build. A successful build proves that source assets compile; it does not replace workflow-level verification against a configured database and external service test environments.

API and access control

The public authentication surface begins at /api/v1/auth. Customer operations are protected by Passport authentication, API throttling, and explicit permissions. The API guide documents the endpoint groups, authentication expectations, and response-testing resources.

API area	Base path	Documentation
Authentication	/api/v1/auth	API guide
Customer account	/api/v1/account	API guide
Shop	/api/v1/shop	API guide
Device tokens	/api/v1/fcm-token	API guide

Repository layout

.
├── app/                 # Laravel application code
├── config/              # Framework and integration configuration
├── database/            # Migrations, factories, and seeders
├── docs/                # Project, architecture, and API documentation
├── frontend/            # React customer application
├── public/              # Public web root
├── resources/           # Laravel views and source assets
├── routes/              # Web and API route definitions
├── storage/postman/     # API request collection
└── tests/               # Laravel tests

Security and operational notes

Kandura handles customer data, payments-adjacent workflows, and administrative capabilities. In production, set APP_ENV=production and APP_DEBUG=false, enforce HTTPS, restrict database and storage access, run queues under a supervised process manager, and configure webhooks with vendor-provided signature verification. Treat signed invoice links as sensitive URLs and avoid logging tokens, payment data, or secrets.

Report a potential vulnerability privately to the repository maintainer. Do not disclose it in a public issue before a fix and coordinated disclosure plan exist.

Documentation index

Document	Description
Architecture guide	Components, data boundaries, request flows, and operational design.
API guide	Endpoint groups, authentication model, and API testing guidance.
Customer application guide	React workspace setup, routes, environment variables, and build commands.

References

[1] Laravel 11 documentation [2] Laravel Passport documentation [3] React documentation [4] Firebase Cloud Messaging documentation [5] Stripe API documentation