@ma7moudsalama/falak-app-duo

falak-app-duo

Vue 3 boilerplate scaffolder. Firebase-free, with Groq moved fully to the backend and Paymob dropped for good. "Duo" = the two remaining bundled integrations on the frontend side: Ably (realtime) and Brevo (email/SMS, proxied through Laravel).

Install & run

Published on npm under both falak-app-duo and the @ma7moudsalama org scope. No install needed — run it straight with npx:

npx falak-app-duo my-project          # interactive prompts
npx falak-app-duo my-project --yes    # all defaults: Ably + Brevo, localhost API, RTL on, no roles/demo
npx falak-app-duo my-project --no-rtl # default locale becomes English/LTR
npx falak-app-duo my-project --roles master,super_admin,admin,user --demo-accounts --demo-data products,orders

Or install the CLI globally once:

npm install -g falak-app-duo
falak-app-duo my-project

The org-scoped equivalent is npx @ma7moudsalama/falak-app-duo my-project.

Feature flags:

• --roles <list> — enable UserRole support for the given comma-separated roles (master,super_admin,admin,user). Any of --roles/--demo-accounts/ --demo-data skips the interactive prompts and uses defaults for the rest.
• --demo-accounts — ship one static demo login per selected role (or a plain demo user when roles are off) that works immediately on the scratch app.
• --demo-data <list> — include static demo rows for the given entities (e.g. products,orders); the demo backend then serves full CRUD for them.

Roles gate the admin dashboard by tier — user:0 < admin:1 < super_admin:2 < master:3:

• Overview + entity CRUD tabs: any admin (tier ≥ 1).
• Users + app-settings tabs (/dashboard): master/super_admin (tier ≥ 2).
• Deleting accounts: master only (tier ≥ 2 can edit roles/status, never their own account or a higher-tier one).

Demo mode

When demo features are selected (demo accounts and/or demo data), .env sets VITE_DATA_MODE=demo. The app then stops calling your API and runs entirely in-browser against src/services/demoApi.js, which mimics the Laravel backend in an IndexedDB database (falak_demo_db): a full sign-up/ sign-in flow, profile + settings writes, the Home /overview stats, generic entity CRUD, and the same /admin/* routes the dashboard panel calls — all behind the same Authorization: Bearer + admin-tier checks. Reuses login info stored in the DB until the seed fingerprint changes. Drop the same frontend on a real backend by setting VITE_DATA_MODE=live (the default without demo features). Client code talks to the data layer through one import, @/services/dataClient, so swapping modes is a single env-var flip.

Auth model

Every request from src/services/api.js carries two headers:

• X-API-Key — identifies this client app, set once per environment in .env.
• Authorization: Bearer <user token> — identifies the logged-in user, issued by your Laravel /auth/login endpoint and stored AES-256 encrypted in IndexedDB (see src/utils/crypto.js, src/storage.js and src/stores/auth.js).

Ably (realtime)

src/services/ably.js wraps Laravel Echo with the ably broadcaster. Private and presence channels are authorized via a custom authorizer that routes through the shared api axios client (POST /broadcasting/auth) instead of a bare fetch — so the same X-API-Key + bearer token gate realtime auth too.

Backend needs:

// config/broadcasting.php
'default' => 'ably',
'connections' => ['ably' => ['driver' => 'ably', 'key' => env('ABLY_KEY')]],

plus BroadcastServiceProvider registered so /broadcasting/auth exists. Only the public half of your Ably key goes in the frontend .env (VITE_ABLY_PUBLIC_KEY) — the secret half stays server-side.

import { listenPrivate, joinPresence } from "@/services/ably";

listenPrivate(`App.Models.User.${userId}`, ".OrderUpdated", (e) => { ... });
joinPresence("chat-room-1", { here: (users) => { ... } });

Brevo (email/SMS)

src/services/brevo.js only calls your own Laravel routes — Brevo's API key is a backend secret and never ships to the browser.

Groq

No frontend code at all now — the backend calls Groq directly and exposes whatever endpoint(s) your app needs (e.g. POST /api/ai/chat). Call that endpoint through the shared api client wherever you need it; there's nothing to scaffold on the client side for it.

Backend routes this frontend expects

POST /api/auth/login       -> { token, user }
POST /api/auth/register    -> { token, user }  (no role sent — backend assigns default)
POST /api/auth/logout
GET  /api/auth/me          -> user
POST /api/broadcasting/auth   (Ably/Echo channel authorization)
POST /api/brevo/email  | /api/brevo/sms | /api/brevo/contacts
GET  /api/admin/overview      (admin tier ≥ 1)
GET  /api/admin/users         (tier ≥ 2)
PUT /api/admin/users/:id      (tier ≥ 2; role/status edits, no self/higher-tier)
DELETE /api/admin/users/:id   (tier ≥ 3, master only)
GET /api/admin/settings   |  PUT /api/admin/settings  (tier ≥ 2)

plus an X-API-Key middleware gating all of the above, and Sanctum (or similar) validating the bearer token for user-scoped routes.

What the CLI does

1. Prints a gradient Falak Duo banner.
2. In interactive mode asks which services to wire up (Ably and/or Brevo), the Laravel API base URL, whether to enable Arabic/RTL by default, and which optional extras to include (UserRole support, demo accounts, demo data entities). --yes takes all defaults (no roles/demo); --no-rtl skips the RTL choice and defaults to English/LTR; any feature flag skips the prompts.
3. Copies templates/default into my-project/, strips the service files and demo-data modules you didn't select, slices the app to your chosen languages, rewrites the role set, and generates a real .env from .env.example with a fresh random AES-256 key + IV, your chosen API base URL, and VITE_DATA_MODE (demo when demo accounts/data are on, else live).
4. Offers to run npm install and start the dev server for you (--yes runs npm install automatically).

To start a scaffolded project on your own:

cd my-project
npm install
npm run dev

Fill in VITE_API_KEY and VITE_ABLY_PUBLIC_KEY in .env before running against a real backend.