# mall — Business Context ## 1. Document Purpose This document is the business reference for the **mall backend system**, covering: * Public / Mobile API * Authenticated customer API * Admin Dashboard * Store / tenant-related functionality * Shared business rules * Content management * Notifications * Commerce-related modules This document explains **what the system does and why**. It does **not** define coding architecture or implementation patterns. Technical implementation rules are defined separately in: * `ARCHITECTURE_RULES.md` * `CLAUDE_INSTRUCTIONS.md` Claude must use all three documents together. --- # 2. Source of Truth When working on mall, use the following priority: 1. Explicit current task requirements 2. `BUSINESS_CONTEXT.md` 3. `ARCHITECTURE_RULES.md` 4. `CLAUDE_INSTRUCTIONS.md` 5. Existing database schema 6. Existing backend implementation 7. Existing API behavior 8. Existing frontend/dashboard behavior Existing code must **not automatically be treated as the business requirement**. Some existing behavior may be: * Legacy behavior * Incomplete behavior * Temporary implementation * Deprecated behavior * Previously implemented requirements that have since changed When a requested change conflicts with existing behavior, Claude must identify the conflict before introducing unrelated changes. --- # 3. Product Overview **mall** is a digital mall / marketplace platform. The platform connects customers with stores, offers, events, products, promotions, and other mall-related services. The backend serves two major consumers: ### Customer-facing API Used by the mobile application and other customer-facing clients. Its responsibility is to expose customer-visible data and execute customer actions. ### Admin Dashboard Used by mall administration and authorized operational users. Its responsibility is to manage platform content, stores, configuration, customers, commercial data, notifications, and operational workflows. The API and Admin Dashboard share the same underlying business domain, but they have different responsibilities and access rules. --- # 4. Main Business Actors ## 4.1 Customer / App User A customer uses the mall application to: * Register and authenticate * Browse stores * Browse categories * Browse offers * Browse events * Browse products where applicable * Discover nearby stores * Search and filter stores * Add/remove favorite stores * Receive notifications * View banners and promotional content * Interact with commercial flows supported by the application * Manage their account Customer-facing endpoints must never expose administrative-only information. --- ## 4.2 mall Admin mall administrators manage the platform through the Admin Dashboard. Depending on permissions, administrative capabilities may include: * Stores * Categories * Zones * Buildings * Units * Products * Bundles * Offers * Events * Banners * Notifications * Vouchers * Settings * Users * Quotations * Orders * Transactions * Invoices * Wallet-related operations * Payment methods * Content and media * Operational reporting Admin privileges must follow the actual permission system implemented by the project. Do not assume every admin account has unrestricted access unless the current authorization model explicitly allows it. --- ## 4.3 Marketing Users Marketing-oriented dashboard users may be responsible for areas such as: * Banners * Campaign content * Events * Offers * Promotional content * Media assets Actual permissions must follow the current role/permission implementation. --- ## 4.4 Commercial / Leasing Users Commercial or leasing users may manage data related to: * Stores * Tenants * Store placement * Zones * Buildings * Units * Commercial information Actual access must follow the implemented permission system. --- ## 4.5 Store / Tenant Users Where store-level access exists, store users operate only within their authorized store scope. They must not gain access to: * Other stores * Global mall configuration * Unauthorized commercial information * Platform-wide administrative functionality Where store-submitted content requires approval, publication must remain controlled by mall administration. --- # 5. High-Level Domain Structure mall contains the following main business domains: ```text mall │ ├── Authentication & Users │ ├── Locations │ ├── Zones │ ├── Buildings │ └── Units │ ├── Stores │ ├── Store Profile │ ├── Store Media │ ├── Store Visibility │ ├── Store Categories │ └── Store Location │ ├── Categories │ ├── Products │ ├── Bundles │ ├── Offers │ ├── Events │ ├── Banners │ ├── Favorites │ ├── Notifications │ ├── Vouchers │ ├── Quotations │ ├── Orders │ ├── Transactions │ ├── Invoices │ ├── Wallet │ ├── Payment Methods │ └── Settings ``` Not every module is necessarily exposed to every user type. --- # 6. API Responsibilities The API is primarily responsible for customer-facing operations. General API responsibilities include: * Authentication * Customer profile management * Public content delivery * Store discovery * Category discovery * Offers * Events * Banners * Favorite stores * Notifications * Location-based store discovery * Commerce-related customer actions * Localized responses The API must respect: * Visibility rules * Active/inactive rules * Date availability * City targeting * Store targeting * User-specific state * Pagination * Authorization Administrative internal fields should not be exposed unless explicitly required. --- # 7. Admin Dashboard Responsibilities The Admin Dashboard acts as the management interface for mall. Its responsibilities include: * CRUD operations for business entities * Content management * Store management * Visibility management * Category management * Offer management * Event management * Banner management * Notification management * Voucher management * Application settings * Commercial data management * Reviewing customer/store related data * Editing configured payment methods * Managing media * Operational workflows Dashboard behavior may differ from API behavior. For example: * Dashboard may show hidden stores. * Public API normally should not. * Dashboard may show expired offers. * Public API should follow customer visibility rules. * Dashboard may manage scheduled notifications. * Customers should only receive them when eligible. --- # 8. Location Structure mall includes a hierarchical physical location domain. Main entities include: ```text Zone ↓ Building ↓ Unit ``` Stores are associated with the appropriate physical location according to the current schema. The existing schema is authoritative regarding exact foreign-key relationships. --- # 9. Zones Zones represent major mall sections / geographical sections. Zones are used for: * Store discovery * Store filtering * Store registration/association * Building organization * Customer navigation * Location-based content mall contains dedicated zone-related experiences. Zone data should support localization where localized fields exist. --- # 10. Buildings Buildings belong to the location hierarchy. Buildings can be used to: * Group stores * Determine nearby stores * Support store selection * Organize units Building data can be dependent on the selected zone. --- # 11. Units Units represent smaller physical locations within buildings. Exact relationships between: * Zone * Building * Unit * Store must follow the current database implementation. Claude must inspect the schema before changing these relationships. --- # 12. Store Registration / Selection Flow Where store registration or store selection is used, the expected dependent flow is: ```text Select Zone ↓ Load Buildings ↓ Select Building ↓ Load Available Stores ↓ Select Store ``` Dependent selections must only expose data belonging to the previous selection. For example: * Building must belong to selected zone. * Store results must belong to the selected building or applicable location. The UI must correctly handle empty states. Known empty-state message: > No stores available for registration. Unavailable dependent selections should remain disabled until their required parent value is selected. Where localized names exist, Arabic/English names should follow the currently selected application language. Account/store activation may require mall administration review where implemented. --- # 13. Stores Stores are one of the central entities in mall. A store can include information such as: * Name * Description * Category * Zone/location * Images * Logo * Contact information * Visibility * Other business information supported by the schema Exact fields must follow the existing model/schema. --- # 14. Store Visibility Stores have a visibility concept. Known behavior: ```text visibility = 1 ``` is the default visible state. A hidden/invisible store must not be treated as a publicly discoverable store in customer-facing experiences where visibility applies. Visibility must be respected by relevant API endpoints. --- # 15. Top Stores Top-store API functionality must respect store visibility. Known rule: ```text visibility = 1 ``` is required for a store to appear in `topStore()` results. A store marked as top but hidden must not appear to customers. --- # 16. Nearby Stores mall provides functionality for retrieving stores near a customer-selected location/building. Known behavior: ```text StoreNearYou(building_id) ``` returns a maximum of: ```text 10 stores ``` The building context must be respected. Nearby-store logic must not expose unrelated or ineligible stores. Visibility and other existing eligibility rules must continue to apply. --- # 17. Favorite Stores Customers can mark stores as favorites. Favorite state is user-specific. Store API resources may expose whether a store is currently favorited by the authenticated user. Known implementation uses an existence relationship similar to: ```text is_favorite ``` Favorite-store listing is paginated. Known page size: ```text 10 stores per page ``` Favorite state must never leak between users. --- # 18. Store Category Filtering Stores can be discovered through categories. mall contains functionality similar to: ```text getStorsByCategoryInZone ``` which supports filtering stores by category within the relevant zone/location context. Category filters must preserve all other applicable restrictions such as: * Zone * Store visibility * Active state where applicable --- # 19. Categories Categories organize stores/products/content according to the implemented relationships. The Admin Dashboard provides category management. Known dashboard filtering requirements: * All * Active * Hidden The category page should expose counts for the relevant states. A category status/visibility column is displayed to distinguish: * Active * Hidden The API should only expose categories according to customer-facing visibility rules. --- # 20. Products mall contains a product domain. Products belong to the appropriate store/category relationships according to the existing schema. Product behavior must follow: * Store ownership * Visibility * Status * Pricing * Availability * Existing category relationships Claude must inspect the current Product model, services, API resources, requests, and dashboard implementation before changing product business behavior. Do not invent inventory, pricing, or stock rules that are not implemented or explicitly requested. --- # 21. Bundles mall includes bundle-related functionality. Bundles may group commercial items according to the existing implementation. Before modifying bundle behavior, Claude must inspect: * Bundle model * Relationships * Pricing rules * Product relationships * Availability * API exposure * Dashboard management No new bundle calculation rule should be inferred without a requirement. --- # 22. Offers Offers are promotional content associated with mall and/or stores according to the existing schema. Offers may be customer-visible through the API and managed through the Admin Dashboard. Offer visibility can depend on: * Status * Publication state * Start date * End date * Store eligibility * Other existing fields Expired or unavailable offers should not be returned as active customer offers when date/status restrictions apply. Administrators may still need to access historical or expired offers. --- # 23. Events Events represent mall events, activities, or promotional activations. Events are: * Managed through Admin Dashboard * Exposed through customer-facing API where eligible * Potential notification targets Events may include: * Images * Dates * Details * Location information * Visibility/status Exact eligibility rules must follow current implementation. --- # 24. Banners Banners are promotional visual content managed by the dashboard and consumed by customer-facing clients. Banner behavior can depend on: * Visibility * Status * Scheduling * Placement * Existing targeting rules Only eligible banners should be exposed to customer-facing clients. --- # 25. Media Management Several mall content modules support image/media management. Known dashboard image-editing requirements apply to: * Stores * Offers * Events * Banners Existing images can be cropped during edit flows. Crop controls should appear directly under the related image where implemented. Image updates must preserve the existing backend storage strategy unless a task explicitly changes it. Claude must not introduce a new storage provider or media architecture without a requirement. --- # 26. Notifications Notifications are an important customer-engagement module. mall notifications support targeting. Known target fields include: ```text store_id city_id event_id offer_id ``` A notification may therefore be associated with: * Store * City * Event * Offer according to its type and configuration. --- # 27. Notification Types Known notification type mapping: ```text 1 = Offers 2 = Stores 3 = Events ``` This mapping must not be changed casually because existing records and clients may depend on these numeric values. If notification types are refactored, backward compatibility must be considered. --- # 28. Notification City Targeting Notifications may target a specific city. Customer notification eligibility follows: ```text notification.city_id IS NULL OR notification.city_id = user.city_id ``` Meaning: * `city_id = NULL` → notification is not restricted to one city. * Specific `city_id` → notification is intended for users of that city. A user must not receive a notification targeted exclusively to another city. --- # 29. Scheduled Notifications Scheduled notifications must not appear as normal active notifications before they become eligible. Existing filtering includes consideration of: ```text scheduled != 1 ``` for customer notification retrieval/counting where applicable. The scheduling flow must remain consistent with the existing implementation. --- # 30. Notification Read Tracking Notification read state is stored separately per user. The read-tracking implementation uses: ```text app_notification_reads ``` A notification being read by one customer must never mark it read for another customer. --- # 31. Notification Read Feature Start Date Notification read-state behavior has a historical compatibility rule. Feature start date: ```text 2026-05-12 00:00:00 ``` Notifications created before that date are treated as already read. Therefore: ```text created_at < 2026-05-12 00:00:00 → is_read = true ``` This avoids turning old historical notifications into unread notifications when the read feature was introduced. --- # 32. Notification Resource `is_read` Expected behavior: ```text if notification.created_at < 2026-05-12 00:00:00 is_read = true else is_read = based on app_notification_reads for current user ``` Read state must always be calculated for the authenticated user. --- # 33. Notification Unread Count Unread notification count must respect: * Notification read start date * Current user * User creation date * City targeting * Scheduling rules * Existing notification eligibility rules Historical notifications that predate the user's relevant notification lifecycle must not incorrectly increase the unread count. --- # 34. Notification Ordering Read/unread state must **not change the natural notification ordering**. Do not implement: ```text Unread notifications first Read notifications second ``` unless explicitly requested. Both read and unread notifications should preserve the intended chronological/business ordering. A read notification should not be pushed to the bottom only because it has been read. --- # 35. Scheduled Notification Ordering Scheduled notifications should be ordered according to the time they effectively become active/sent where applicable. Using only the original database `created_at` may create incorrect chronology when a notification was created earlier but scheduled for later. The effective notification time must be considered by the existing scheduling logic. --- # 36. Vouchers mall supports vouchers. Known voucher fields include: ```text approved added_type ``` Known defaults: ```text approved = 1 added_type = mall ``` Known `added_type` values include: ```text mall store ``` Meaning vouchers can be differentiated based on who/what added them. Any approval or store-specific redemption behavior beyond existing implementation must be inspected before modification. --- # 37. Payment Methods The current mall Admin Dashboard manages a predefined set of payment methods. Known current business behavior: * Existing payment methods can be edited. * Admin does not dynamically create arbitrary new payment methods from the dashboard. Therefore: ```text Edit existing payment method → Supported Add arbitrary new payment method → Not currently supported ``` Adding a new payment method may require development work because payment methods can have implementation-specific behavior and integrations. Claude must not convert payment methods into fully dynamic records unless this is explicitly approved as a new business requirement. --- # 38. Quotations mall contains quotation-related functionality. Quotation behavior must be taken from the current implementation. Before modifying quotation logic, inspect: * Models * Statuses * Store/customer relationships * Pricing * API endpoints * Admin actions * Order conversion behavior if any Do not infer a quotation lifecycle from generic e-commerce behavior. --- # 39. Orders mall contains order-related functionality. Orders represent commercial transactions/workflows according to the existing implementation. Before changing any order flow, inspect the exact existing: * Status values * Status transitions * Payment linkage * Customer linkage * Store linkage * Invoice behavior * Cancellation logic * Administrative actions Never introduce a new order status or status transition without checking all consumers. --- # 40. Transactions Financial transaction functionality must be treated as business-critical. Changes affecting: * Amount * Payment status * Payment reference * Order linkage * Wallet * Invoice * Refund behavior require inspection of the full related workflow. Do not make isolated changes to transaction calculations without tracing their consumers. --- # 41. Invoices Invoice functionality is related to the relevant commerce/payment flow. Before modifying invoice behavior, inspect: * When invoices are created * Which transaction/order creates them * Invoice amount sources * File generation * Customer/store association * Dashboard visibility * API exposure Financial values in invoices must come from authoritative transaction/order calculations rather than independently recomputing values unless the architecture explicitly defines otherwise. --- # 42. Wallet mall contains wallet-related functionality. Wallet changes are financially sensitive. Before changing wallet balances, Claude must inspect: * Credit operations * Debit operations * Transaction relationships * Balance calculation * Idempotency behavior * Admin adjustments * User ownership Never update wallet balance logic based on assumptions. --- # 43. Settings mall contains configurable application settings. Settings may control application behavior without requiring code changes. Before introducing a new hard-coded value, inspect whether an equivalent platform setting already exists. Similarly, do not move critical logic to settings if the value is intended to be fixed business behavior. --- # 44. Localization mall supports: * Arabic * English Localized entities may contain separate Arabic and English values. The API must expose text according to the project's existing localization strategy. Dashboard forms may allow administrators to manage both languages. Do not remove one language field because only one is currently visible in a specific client. --- # 45. API Resource Rules Customer-facing API Resources should return only information needed by the client. Resources may include calculated user-specific fields such as: ```text is_favorite is_read ``` These fields must be calculated in the context of the authenticated user. Do not expose: * Internal administrative metadata * Sensitive implementation details * Unnecessary database fields * Other users' state --- # 46. Pagination Existing endpoint-specific pagination behavior must be preserved unless explicitly changed. Known example: ```text Favorite Stores → 10 per page ``` Not every endpoint must use the same pagination size. Do not globally change pagination while fixing one endpoint. --- # 47. Status and Visibility Concepts mall contains multiple concepts that must not be confused: ```text Active Inactive Visible Hidden Approved Pending Scheduled Expired Published ``` Their meaning depends on the entity. For example: ```text Store visibility ``` is not automatically equivalent to: ```text Store active status ``` Claude must inspect each entity before merging or reusing status logic. --- # 48. Public Visibility Principle Customer-facing APIs should generally return only content that is eligible for public/customer visibility. Eligibility may include: ```text active AND visible AND approved AND within valid date range AND matches location/city targeting ``` but the exact conditions differ by module. Do not blindly apply the same scope to every entity. Use each module's actual business rules. --- # 49. Admin Visibility Principle The Admin Dashboard may need access to data that is hidden from customers. For example, administrators may need to see: * Hidden stores * Inactive categories * Expired offers * Scheduled notifications * Archived records * Pending content Therefore, customer-facing API scopes must not accidentally be applied to Admin Dashboard queries unless intended. --- # 50. Content Lifecycle Where supported by the existing module, content may conceptually move through states such as: ```text Draft → Review → Approved → Published → Unpublished / Archived ``` Scheduling may also apply to certain content. However, Claude must **not add this lifecycle to a module solely because it appears in this document**. Only use lifecycle states that are supported by the current database or explicitly required by a task. --- # 51. Search and Discovery mall discovery can involve filters such as: * Store name * Category * Zone * Building * Merchant/store type * Other implemented filters Search logic must maintain existing visibility and eligibility restrictions. Searching must never bypass business filters simply because a text match exists. --- # 52. Dashboard Forms Admin forms must follow the entity's business requirements. Common form responsibilities include: * Validation * Arabic/English content * Media upload * Image crop * Status * Visibility * Relationships * Scheduling where supported Edit forms must preserve existing values unless explicitly changed by the administrator. --- # 53. Delete Behavior Deletion behavior varies by entity. Claude must inspect whether an entity uses: * Hard delete * Soft delete * Disable/inactive status * Archive * Relationship restrictions Never replace one deletion strategy with another without understanding dependent records. --- # 54. Data Integrity Business relationships must remain valid. Examples: * Store/category relationships * Store/location relationships * Offer/store relationships * Notification target relationships * Order/customer relationships * Financial record relationships Never bypass foreign-key or domain restrictions just to make an operation succeed. --- # 55. Financial Safety The following modules are financial or potentially financial: * Orders * Transactions * Invoices * Wallet * Vouchers * Payment methods * Quotations where pricing is involved Changes to these modules require special care. Before modifying a financial flow: 1. Identify the authoritative amount source. 2. Identify all dependent records. 3. Identify status transitions. 4. Identify API consumers. 5. Identify dashboard consumers. 6. Check historical data compatibility. 7. Check duplicate/idempotency risks. --- # 56. Backward Compatibility mall has existing API consumers. Changes must consider backward compatibility for: * Field names * Enum/numeric values * Resource structure * Pagination * Notification types * Status values * Existing mobile application behavior Do not rename or remove an API field solely for internal code cleanliness. Breaking API changes require explicit approval. --- # 57. API vs Dashboard Separation The same entity may behave differently depending on consumer. Example: ```text Store ``` ### Admin Dashboard May access: * Visible * Hidden * Active * Inactive * Administrative metadata ### Customer API Should return only stores eligible for customer exposure. Another example: ```text Notification ``` ### Admin Dashboard Can manage: * Draft/configured notifications * Targeting * Scheduling * Related offer/store/event ### Customer API Returns only notifications eligible for that specific user. This separation must be preserved. --- # 58. Existing Behavior Preservation When implementing a task, Claude should preserve unrelated existing business behavior. For example: If the task is: > Add category filter to store listing Claude should not simultaneously change: * Favorite calculation * Store visibility * Pagination size * Sorting * API response format unless those changes are required for the task. --- # 59. No-Assumption Rule If Claude finds an entity or behavior that is not sufficiently documented here, it must inspect the existing implementation before deciding how it works. Inspect relevant: * Migration/schema * Model * Repository * Service * Controller * Request * Resource * Livewire/Admin component * Routes * Tests Do not assume generic e-commerce behavior. mall business behavior is authoritative over generic conventions. --- # 60. Important Known Business Rules Summary The following rules are currently known and should be treated as important: ### Stores ```text Default visibility = 1 Hidden stores must not appear in topStore(). ``` ### Nearby Stores ```text StoreNearYou(building_id) Maximum results = 10 ``` ### Favorites ```text Favorite store listing = 10 per page Favorite state is per-user ``` ### Categories Dashboard filters: ```text All Active Hidden ``` ### Notifications Types: ```text 1 = Offers 2 = Stores 3 = Events ``` City targeting: ```text city_id IS NULL OR city_id = current_user.city_id ``` Read feature start: ```text 2026-05-12 00:00:00 ``` Before this date: ```text is_read = true ``` Read/unread status must not change notification ordering. ### Vouchers Defaults: ```text approved = 1 added_type = mall ``` Supported source values include: ```text mall store ``` ### Payment Methods ```text Edit predefined payment methods = Supported Create arbitrary payment method = Not currently supported ``` ### Store Registration Dependent selection: ```text Zone → Building → Store ``` Activation/review behavior must follow current administration workflow. --- # 61. Claude Working Rule for mall Before implementing any non-trivial mall task, Claude should answer internally: ```text 1. Which business module is affected? 2. Is this Admin, API, or both? 3. Who is the actor? 4. What existing business rule applies? 5. What existing API behavior must remain compatible? 6. What related entities can be affected? 7. Is there user-specific state? 8. Is there visibility/status/date filtering? 9. Is there financial impact? 10. What tests prove the behavior? ``` The task should then be implemented with the smallest safe scope. --- # 62. mall Core Principle The central rule when maintaining mall is: > Understand the business flow first, then modify the implementation. Existing code is evidence of current behavior, but business rules and approved requirements determine the intended behavior. Changes must preserve: * Data integrity * Customer isolation * Store isolation * Admin authorization * API compatibility * Visibility rules * Localization * Financial correctness * Existing unrelated functionality