Skip to main content
ShumoulShumoul Developer Portalplatform.shumoul.com
Version: Latest

19. Angular Developer Brief — Arabic / English

شرح مبرمج Angular — عربي / English​

This page is the companion brief prepared for the Angular developer implementing the onboarding UI. It is reproduced from the original bilingual brief distributed to the frontend team, restructured into unified bilingual topics for the documentation site. The API contract, permission names, endpoint names, and user journey below are unchanged from the original brief and from Chapter 8 / Chapter 9 of this guide — this page adds structure and cross-references, it does not redefine anything.

Downloads:

19.1 Purpose of this document / الغرض من الملف​

العربية: هذا الملف يشرح لمبرمج Angular ما هي ميزة تهيئة النشاط الذكية، لماذا بُنيت، كيف تعمل من أول تسجيل دخول، وما المطلوب تنفيذه في الواجهة دون الحاجة لفهم تفاصيل الباك إند الداخلية.

English: This file explains the Business Onboarding feature to the Angular developer from zero to implementation: what it does, how the API flow works, what the UI must build, and what must not be done on the frontend.

Prepared for: Shumoul Angular developer · Reference: docs.shumoul.com → Business Onboarding & Smart Configuration

19.2 What the Angular developer needs to build​

العربية: الواجهة لا تقرر الإعدادات. الواجهة فقط تعرض الأسئلة، تحفظ الإجابات، تعرض التوصية، ثم ترسل طلب تطبيق الإعدادات. القرار الكامل موجود في API.

English: The frontend does not decide which settings to enable. The backend owns all recommendation and settings-patch logic. Angular only renders, collects answers, previews the recommendation, and calls the public onboarding endpoints.

Key rule / قاعدة أساسية: Angular must never call the internal backend apply endpoint — use only /api/v1/onboarding/* endpoints. يجب على Angular ألا يستدعي أبدًا endpoint الداخلي الخاص بالباك إند.

Hard rules — things Angular must not do / أشياء ممنوعة على Angular​

  • لا تستدعِ /api/internal/onboarding/apply-settings-patch — do not call the internal endpoint, ever.
  • لا تخزن أي Internal API Key في Angular — never store the internal API key in the frontend.
  • لا تقرر الإعدادات من الواجهة — do not decide settings on the frontend.
  • لا تكتب الأسئلة بشكل ثابت داخل الكود — do not hard-code the questionnaire.
  • لا تتجاوز 403 أو تعتبرها bug — do not bypass a 403 or treat it as a backend bug.
  • لا تعتمد على tenant 555001 داخل الكود؛ هذا مجرد تينانت اختبار — do not hard-code the 555001 test tenant; it is a dev fixture only.
  • لا تعدل عقود API من الواجهة — do not modify the API contract from the frontend.

19.3 High-level user journey / رحلة المستخدم​

العربية — متى يظهر الاستبيان؟ الاستبيان لا يظهر داخل شاشة التسجيل الأولى. السيناريو الصحيح هو:

  1. المشترك يسجل بيانات الاشتراك.
  2. النظام يرسل OTP أو رابط تحقق حسب النظام الحالي.
  3. بعد التفعيل، يسجل المستخدم الدخول.
  4. بعد نجاح الدخول، Angular يستدعي endpoint حالة الاستبيان.
  5. إذا كان الاستبيان مطلوبًا، يتم توجيه المستخدم إلى شاشة تهيئة النشاط بدل لوحة التحكم.
  6. بعد إكمال التهيئة بنجاح، يدخل المستخدم إلى لوحة التحكم.

English — when should it appear? The onboarding survey should appear after account activation and after the first successful login. It should not be part of the initial registration form.

  1. User registers a new subscription.
  2. Account is activated through OTP or the current activation flow.
  3. User logs in for the first time.
  4. Angular calls GET /api/v1/onboarding/status.
  5. If onboarding is required, redirect to /onboarding/setup.
  6. After successful apply or skip, redirect to the dashboard.

Required Angular flow, step by step / رحلة Angular المطلوبة​

  1. بعد Login ناجح، خذ الـ token من النظام الحالي. / After successful login, store the token using the existing auth flow.
  2. استدعِ GET /api/v1/onboarding/status. / Call GET /api/v1/onboarding/status.
  3. إذا isRequired = true، وجّه المستخدم إلى /onboarding/setup. / If isRequired is true, route to /onboarding/setup.
  4. إذا isRequired = false، وجّه المستخدم إلى لوحة التحكم. / If isRequired is false, continue to the normal dashboard.
  5. اعرض الأسئلة ديناميكيًا من GET /api/v1/onboarding/survey?lang=ar. / Load the survey using GET /api/v1/onboarding/survey?lang=ar and render questions dynamically.
  6. بعد نهاية الأسئلة، أرسل الإجابات إلى POST /api/v1/onboarding/answers. / Save answers using POST /api/v1/onboarding/answers.
  7. بعد نجاح الحفظ، استدعِ POST /api/v1/onboarding/recommendation. / Generate the recommendation using POST /api/v1/onboarding/recommendation.
  8. اعرض شاشة مراجعة التوصية. / Show the recommendation preview screen.
  9. عند ضغط تطبيق الإعدادات، استدعِ POST /api/v1/onboarding/apply. / Apply using POST /api/v1/onboarding/apply.
  10. بعد النجاح، اعرض شاشة نجاح ثم وجّه المستخدم إلى لوحة التحكم. / Show a success screen and redirect to the dashboard.

Do not show the main dashboard before checking onboarding status, and avoid redirect loops between the dashboard and the onboarding route.

19.4 Backend readiness summary​

The backend for Business Onboarding & Smart Configuration is complete and secured (see Chapter 18 — Phase History for full detail):

  • Onboarding backend flow is live-tested.
  • /apply changes tenant AppSettings successfully.
  • CostCenterSettings is supported.
  • JWT authentication works.
  • [MustHavePermission] is enforced.
  • Onboarding.View is available to authenticated tenant users.
  • Onboarding.Answer / Recommendation / Apply / Skip require the tenant Admin role.
  • Angular must use the normal Authorization: Bearer <token> header.
  • Angular must never call the internal BackEnd endpoint directly.

19.5 API endpoints / Endpoints التي سيستخدمها Angular​

MethodEndpointالغرضPurposeالصلاحية / Permission
GET/api/v1/onboarding/statusمعرفة هل الاستبيان مطلوب أم لاCheck onboarding stateView
GET/api/v1/onboarding/survey?lang=arجلب الأسئلة والخطوات والخياراتLoad survey definitionView
POST/api/v1/onboarding/answersحفظ إجابات المستخدمSave answersAnswer — Admin only
POST/api/v1/onboarding/recommendationتوليد التوصيةGenerate recommendationAnswer — Admin only
POST/api/v1/onboarding/applyتطبيق الإعداداتApply recommended settingsApply — Admin only
POST/api/v1/onboarding/skipتخطي الاستبيانSkip onboardingSkip — Admin only

Full request/response examples for every endpoint are in Chapter 8 — API Reference.

19.6 Authentication and authorization / منطق الصلاحيات​

العربية: الواجهة يجب أن تفهم أن ليس كل مستخدم داخل المنشأة يحق له تطبيق إعدادات الاستبيان. الباك إند يعتمد على JWT عادي، ويعتبر المستخدم Admin إذا كان لديه role claim بقيمة Admin.

English: All requests must use the normal Authorization: Bearer <token> header from the existing login flow. The backend detects tenant admin users from the JWT role claim. Non-admin tenant users can read status and survey, but answers/recommendation/apply/skip will return 403.

الحالة / Caseالتصرف المتوقع في Angular / Expected Angular behavior
مستخدم مصادق داخل التينانت / Authenticated tenant userيمكنه استدعاء status و survey. / Can read status/survey.
مستخدم غير Admin / Not an Adminقد يحصل على 403 عند save/recommend/apply/skip. يجب عرض رسالة واضحة. / May receive 403 for sensitive actions — show a clear message.
مستخدم Admin / Tenant Adminيستطيع إكمال الاستبيان وتطبيق الإعدادات. / Can complete and apply onboarding.
بدون Token أو منتهي / No or expired tokenيتم تحويله إلى Login. / Redirect to login.
Internal apply endpointNever call it from Angular / لا يُستدعى أبدًا من Angular.

The full claim-level detail (which role claim, why Admin specifically, cross-tenant safety) is in Chapter 9 — Authentication & Authorization.

19.7 First login routing behavior​

The routing decision is a single branch on status.isRequired, checked immediately after login and before any dashboard content is shown:

  • isRequired: true → route to /onboarding/setup (اعرض شاشة تهيئة النشاط بدل لوحة التحكم).
  • isRequired: false → continue to the normal dashboard (تابع إلى لوحة التحكم مباشرة).

Do not perform this check anywhere other than right after login — do not show onboarding from a menu item or re-trigger it once a session has already passed the check for the current login, to avoid redirect loops.

19.8 Dynamic survey rendering / عرض الأسئلة ديناميكيًا​

العربية: لا تكتب الأسئلة داخل Angular بشكل ثابت. الأسئلة تأتي من API وفيها نوع السؤال والخيارات وقاعدة الظهور VisibleWhen.

English: Angular must render questions based on the survey API response. Do not hard-code the questionnaire. Each question contains a type, labels, options, a required flag, and optional VisibleWhen metadata.

Supported question types / أنواع الأسئلة المطلوبة:

  • SingleChoice
  • MultiChoice
  • Boolean
  • Number
  • Text

The live survey response (see Chapter 8) uses SingleChoice/MultiChoice/Boolean today; Number and Text are supported question types the renderer should handle even if the current default survey doesn't use them yet.

19.9 VisibleWhen logic​

مثال: إذا كان السؤال يظهر فقط للمطاعم والكافيهات — show the question only when answers.activityType === "RestaurantCafe":

{ "activityType": "RestaurantCafe" }

ومثال سؤال يظهر فقط إذا كانت المنشأة تستخدم الضريبة — show only when answers.usesVat === true:

{ "usesVat": true }

Rule of implementation: if visibleWhen is null/absent, the question is always visible; otherwise it is visible only when every key in visibleWhen matches the corresponding saved answer exactly.

19.10 Recommendation preview​

After POST recommendation, show a review screen — not the raw JSON — containing:

  • Profile name (profileNameAr / profileNameEn)
  • Confidence percentage (confidence)
  • Summary (summary, bilingual)
  • Settings groups included (settingsPatch keys, for an advanced/technical view only)
  • Warnings (warnings)
  • Next actions (nextActions)

اعرض شاشة مراجعة التوصية قبل التطبيق — treat this as a genuine confirmation step, not a silent pass-through; apply changes real tenant settings. See Chapter 8.4 for the full response shape.

19.11 Apply settings flow​

عند ضغط "تطبيق الإعدادات"، استدعِ POST /api/v1/onboarding/apply:

{
  "sessionId": "<session id from recommendation>",
  "acceptAll": true,
  "overrides": null
}
  • Show a loading state: "جاري تطبيق الإعدادات..."
  • On success: show a success screen, then redirect to the dashboard.
  • On failure: stay on the recommendation screen and show a clear error — do not silently retry or discard the recommendation.

overrides exists in the contract but is not processed in the current backend phase — always send acceptAll: true and overrides: null; do not build partial-acceptance UI yet (see Known Limitations).

19.12 Skip flow​

POST /api/v1/onboarding/skip bypasses onboarding entirely. Only show the "تخطي الآن" (Skip) action when status.canSkip is true. After a successful skip, the session is Skipped and the dashboard opens normally — onboarding should not be shown again for that tenant (test case 5 in §19.16).

19.13 Error handling / الأخطاء المتوقعة​

الكود / HTTPالمعنى / Meaningما يعرضه Angular / UI behavior
401المستخدم غير مصادق أو التوكن غير صالح / Unauthorized or expired tokenتحويل إلى Login / Redirect to login
403لا يملك صلاحية الإجراء / User lacks required permissionإظهار أن الإجراء متاح فقط لمدير المنشأة / Show admin-required message
501جسر تطبيق الإعدادات غير مفعل / Apply bridge is disabledإظهار رسالة تواصل مع الدعم / Show support/contact message
500خطأ عام في الخادم / Server errorرسالة خطأ ودية مع زر إعادة المحاولة / Friendly error + retry
Network Errorانقطاع اتصال / Connection issueزر إعادة المحاولة / Show retry option

19.14 Admin-only behavior​

Backend restricts sensitive actions to the tenant Admin role — status/survey may work for any authenticated tenant user, while answers/recommendation/apply/skip may return 403 for a non-admin user. Do not treat a 403 here as a backend bug.

When a 403 occurs on a sensitive action, show:

إكمال تهيئة النشاط متاح فقط لمدير المنشأة. (Completing the business setup is only available to the tenant's administrator.)

19.15 UI copy in Arabic / شكل الواجهة المطلوب​

الواجهة يجب أن تكون عربية أولًا، RTL، واحترافية، وليست نموذجًا عاديًا مملًا — Arabic-first, RTL, professional, not a plain boring form. Use card-based options, a stepper for progress, and Shumoul's blue-and-white colors.

Recommended screens:

  • صفحة ترحيب / Welcome screen
  • Stepper من خمس خطوات تقريبًا / Survey stepper screen (~5 steps)
  • بطاقات لاختيار نوع النشاط / Question renderer component (card-based options)
  • شاشة مراجعة التوصية قبل التطبيق / Recommendation preview screen
  • حالة Loading أثناء تطبيق الإعدادات / Apply loading state
  • شاشة نجاح بعد التطبيق / Success screen
  • رسائل خطأ واضحة ومفهومة / Error state
  • (اختياري) نافذة تأكيد التخطي / Optional skip confirmation dialog

Suggested UI copy (use verbatim or adapt minimally):

ScreenArabic copy
Welcome titleلنجهز شمول بما يناسب نشاطك
Welcome subtitleأجب عن بعض الأسئلة البسيطة وسنقوم بضبط إعدادات النظام تلقائيًا.
Survey titleتهيئة نشاطك
Recommendation titleالإعدادات المقترحة لمنشأتك
Apply buttonتطبيق الإعدادات
Skip buttonتخطي الآن
Success titleتمت تهيئة نشاطك بنجاح

19.16 Testing checklist​

قائمة قبول قبل التسليم / Acceptance checklist​

  • بعد Login يتم فحص onboarding/status قبل فتح الداشبورد. / Onboarding status is checked after login before dashboard navigation.
  • إذا isRequired=true يتم فتح /onboarding/setup. / If isRequired is true, /onboarding/setup opens.
  • الأسئلة تظهر ديناميكيًا من API. / Survey is rendered dynamically from the API.
  • VisibleWhen يعمل. / VisibleWhen logic works.
  • حفظ الإجابات يعمل للمستخدم Admin. / Admin users can save answers, generate recommendation, and apply.
  • غير Admin يحصل على رسالة واضحة عند 403. / Non-admin users receive a clear 403 message for sensitive actions.
  • التوصية تظهر بشكل مفهوم بدون عرض JSON خام كواجهة رئيسية. / Recommendation preview is user-friendly and does not expose raw JSON as the main UI.
  • تطبيق الإعدادات ينجح ويعرض شاشة نجاح. / Apply success redirects to the dashboard.
  • بعد Applied لا يظهر الاستبيان مرة أخرى. / Applied/Skipped status no longer opens onboarding.
  • لا توجد مفاتيح أو endpoints داخلية في كود Angular. / Angular never calls internal endpoints and never stores internal API keys.

Specific test cases (dev tenant only)​

Use tenant 555001 / مطاعم شواطئ عدن only as a dev fixture — do not hard-code it in application code.

  1. No token → redirect to login.
  2. Valid tenant Admin token → full flow succeeds.
  3. Valid normal (non-admin) tenant user → status/survey may work, sensitive actions return 403.
  4. Applied status → no onboarding redirect.
  5. Skipped status → dashboard opens normally.
  6. API 501 → show support message.
  7. Network error → show retry.

19.17 Claude Code prompt for the Angular developer​

The Angular developer can copy the prompt below into Claude Code inside the Angular project. It is intentionally written in English because the codebase, APIs, routes, and DTOs use English names. This is the same prompt distributed in the original brief, reproduced verbatim so it stays copy-paste ready from the documentation site directly — see also the general-purpose version in Chapter 13.2 if your project conventions differ from what's assumed below.

# Task: Phase 2 — Angular First Login Onboarding UI

We have completed and secured the backend for Business Onboarding & Smart Configuration.

Backend status:
- Onboarding backend flow is live-tested.
- /apply changes tenant AppSettings successfully.
- CostCenterSettings is supported.
- JWT authentication works.
- [MustHavePermission] is enforced.
- Onboarding View is available to authenticated tenant users.
- Onboarding Answer / Recommendation / Apply / Skip require tenant Admin role.
- Angular must use the normal Authorization: Bearer <token> header.
- Angular must never call the internal BackEnd endpoint directly.

Do not implement backend changes.
Do not bypass authorization.
Do not hard-code tenant IDs.
Do not hard-code survey questions.
Do not call /api/internal/onboarding/apply-settings-patch.
Do not expose any internal API key.
Do not implement registration/OTP/WhatsApp in this phase.

## Backend Endpoints

Use these endpoints:

GET  /api/v1/onboarding/status
GET  /api/v1/onboarding/survey?lang=ar
POST /api/v1/onboarding/answers
POST /api/v1/onboarding/recommendation
POST /api/v1/onboarding/apply
POST /api/v1/onboarding/skip

All requests must use the existing authenticated HTTP client/interceptor.

## Main User Journey

After successful login:
1. Store token using the existing auth flow.
2. Call GET /api/v1/onboarding/status.
3. If isRequired = true, redirect user to /onboarding/setup.
4. If isRequired = false, continue to the normal dashboard.

Do not show the main dashboard before checking onboarding status.
Avoid redirect loops and never call the internal apply endpoint from Angular.

## Required Routes

Add routes:
- /onboarding/setup
- /onboarding/recommendation
- /onboarding/success

Use existing auth guards.

## Angular Service

Create OnboardingService with these methods:
- getStatus()
- getSurvey(lang: string)
- saveAnswers(answers: Record<string, any>)
- generateRecommendation()
- applyRecommendation(sessionId: string)
- skip()

Use the existing API base URL and HTTP interceptor pattern.

## Survey Rendering

Render questions dynamically from the survey API response.
Supported question types:
- SingleChoice
- MultiChoice
- Boolean
- Number
- Text

Implement simple VisibleWhen logic:
- If null or empty, question is visible.
- If { "activityType": "RestaurantCafe" }, show only when answers.activityType === "RestaurantCafe".
- If { "usesVat": true }, show only when answers.usesVat === true.

Do not hard-code the questionnaire.

## Recommendation Preview

Show:
- Profile name
- Confidence percentage
- Summary
- Settings groups included
- Warnings
- Next actions

Do not show raw JSON as the main UI.

## Apply Flow

When user clicks "تطبيق الإعدادات", call POST /api/v1/onboarding/apply:

{
  "sessionId": "<session id>",
  "acceptAll": true,
  "overrides": null
}

Show loading: "جاري تطبيق الإعدادات..."
On success, show success screen and redirect to dashboard.
On failure, stay on recommendation screen and show a clear error.

## Admin Permission UX

Backend restricts sensitive actions to tenant Admin.
- status/survey may work for normal tenant users.
- answers/recommendation/apply/skip may return 403 for non-admin users.

If 403 occurs, show:
"إكمال تهيئة النشاط متاح فقط لمدير المنشأة."

Do not treat 403 as a backend bug.

## Error Handling

401: redirect to login.
403: show admin-required permission message.
501: show "تطبيق الإعدادات غير مفعل حاليًا. تواصل مع الدعم."
500: show friendly generic error.
Network error: show retry option.

## UI Requirements

Arabic first.
RTL.
Use Shumoul colors.
Professional SaaS onboarding style.
Use card-based options, stepper progress, and responsive layout.

Suggested UI copy:
- Welcome title: "لنجهز شمول بما يناسب نشاطك"
- Subtitle: "أجب عن بعض الأسئلة البسيطة وسنقوم بضبط إعدادات النظام تلقائيًا."
- Survey title: "تهيئة نشاطك"
- Recommendation title: "الإعدادات المقترحة لمنشأتك"
- Apply button: "تطبيق الإعدادات"
- Skip button: "تخطي الآن"
- Success title: "تمت تهيئة نشاطك بنجاح"

## Testing

Use tenant 555001 / مطاعم شواطئ عدن only as a dev fixture. Do not hard-code it.

Test:
1. No token -> redirect to login.
2. Valid tenant Admin token -> full flow succeeds.
3. Valid normal tenant user -> status/survey may work, sensitive actions return 403.
4. Applied status -> no onboarding redirect.
5. Skipped status -> dashboard opens normally.
6. API 501 -> show support message.
7. Network error -> show retry.

## Final Report Required

At the end provide:
- Files created and modified.
- Routes added.
- Components created.
- Service methods added.
- Guards/hooks added.
- How status is checked after login.
- How dynamic survey rendering works.
- How VisibleWhen works.
- How recommendation preview works.
- How apply works.
- How 403 admin-only behavior is handled.
- Test results with tenant 555001.
- Screenshots or UI description.
- Remaining limitations.

19.18 Final notes / ملاحظة نهائية​

العربية: استخدم docs.shumoul.com كمرجع رسمي. هذا الملف مرفق عملي لتنفيذ Angular ويجب مشاركته مع مبرمج الواجهة مع رابط التوثيق.

English: Use docs.shumoul.com as the official reference. This file is a practical companion for the Angular implementation and should be shared with the frontend developer together with the documentation link.

For the complete technical reference behind every rule summarized on this page — architecture, database tables, the settings patch engine, internal bridge security, and the full phase-by-phase hardening history — see the rest of this section starting from the Cover and Table of Contents.