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-related functionality Shared business rules Content management Notifications Commerce-related modules Physical mall location structure 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. Project Origin Mall was initially created from the existing mall codebase. The mall implementation is a technical baseline, but it must not automatically be treated as the final Mall business specification. Existing mall behavior may be: Reused as-is Modified for Mall Replaced Deprecated Removed Mall-specific requirements in this document always take priority over inherited mall behavior. 3. Source of Truth When working on Mall, use the following priority: Explicit current task requirements BUSINESS_CONTEXT.md ARCHITECTURE_RULES.md CLAUDE_INSTRUCTIONS.md Existing database schema Existing backend implementation Existing API behavior Existing dashboard behavior Existing code is evidence of current behavior, but it is not automatically the business requirement. When a requested change conflicts with inherited behavior, Claude must identify the conflict and implement the Mall requirement without introducing unrelated changes. 4. Product Overview Mall is a digital mall / marketplace platform. The platform connects customers with: Stores Categories Products Offers Events Promotional content Mall locations Commercial services The backend serves two major consumers: Customer-facing API Used by mobile applications and other customer-facing clients. Its responsibility is to: Expose customer-visible data Execute customer actions Apply visibility and eligibility rules Return localized API responses Protect user-specific data and state Admin Dashboard Used by Mall administration and authorized operational users. Its responsibility is to: Manage platform content Manage stores Manage mall location structure Manage commercial data Manage notifications Manage settings Manage operational workflows The API and Admin Dashboard share the same business domain, but they have different responsibilities and access rules. 5. Main Business Actors 5.1 Customer / App User A customer may use the Mall application to: Register and authenticate Manage account/profile Browse stores Browse categories Browse offers Browse events Browse products where applicable Discover stores by mall location Add/remove favorite stores Receive notifications View banners and promotional content Use supported commercial flows Customer-facing APIs must never expose administrative-only information. 5.2 Mall Admin Mall administrators manage the platform through the Admin Dashboard. Depending on permissions, administrative capabilities may include: Zones Buildings Floors Units Stores Categories Products Bundles Offers Events Banners Notifications Vouchers Users Quotations Orders Transactions Invoices Wallet-related operations Payment methods Settings Media Operational reporting Admin privileges must follow the actual permission system implemented in the project. Do not assume every admin account has unrestricted access unless the authorization model explicitly allows it. 5.3 Marketing Users Marketing-oriented dashboard users may manage areas such as: Banners Campaign content Events Offers Promotional content Media assets Actual permissions must follow the implemented role/permission system. 5.4 Commercial / Leasing Users Commercial or leasing users may manage data related to: Stores Tenants Store placement Zones Buildings Floors Units Commercial information Actual access must follow the implemented permission system. 5.5 Store / Tenant Users Where store-level access exists, store users must 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. 6. High-Level Domain Structure Mall │ ├── Authentication & Users │ ├── Locations │ ├── Zones │ ├── Buildings │ ├── Floors │ └── 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 actor. 7. API Responsibilities The API is primarily responsible for customer-facing operations. General API responsibilities include: Authentication Customer profile management Public content delivery Store discovery Location-based discovery Category discovery Offers Events Banners Favorite stores Notifications Commerce-related customer actions Localized responses The API must respect: Visibility rules Active/inactive rules Approval state Date availability City targeting Location targeting Store targeting User-specific state Pagination Authorization Administrative internal fields should not be exposed unless explicitly required. 8. Admin Dashboard Responsibilities The Admin Dashboard is the management interface for Mall. Its responsibilities include: CRUD operations for business entities Location hierarchy management Store management Content management Visibility management Category management Offer management Event management Banner management Notification management Voucher management Settings Commercial data management Reviewing customer/store data Editing configured payment methods Media management 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. 9. Mall Physical Location Hierarchy Mall uses the following physical location hierarchy: Zone ↓ Building ↓ Floor ↓ Unit ↓ Store This hierarchy is a core Mall business rule. The inherited mall direct structure: Zone → Building → Unit → Store must not be used in Mall. Mall introduces Floor as a first-class business entity between Building and Unit. 10. Location Relationships 10.1 Zone A Zone can have multiple Buildings. A Building belongs to one Zone. 10.2 Building A Building belongs to one Zone. A Building can have multiple Floors. 10.3 Floor A Floor belongs to one Building. A Floor can have multiple Units. 10.4 Unit A Unit belongs to one Floor. A Unit represents a physical commercial location within the mall. 10.5 Store A Store is assigned to the appropriate Unit according to the current store-location model. A Store must not be assigned to a Unit that belongs to a different selected Floor/Building/Zone chain. 11. Dependent Location Selection Flow Any relevant Admin Dashboard or API flow must follow: Select Zone ↓ Load Buildings ↓ Select Building ↓ Load Floors ↓ Select Floor ↓ Load Units ↓ Select Unit ↓ Assign / Select Store Every dependent request must validate parent-child ownership. Examples: Building must belong to selected Zone. Floor must belong to selected Building. Unit must belong to selected Floor. Store assignment must use the intended Unit. Dependent selections should remain disabled until their required parent value is selected. Empty states must be handled clearly. 12. Location Data Integrity Rules The following invalid relationships must be rejected: Building from another Zone Floor from another Building Unit from another Floor Store linked to an inconsistent Unit hierarchy Changing a parent relation must not leave invalid descendants. Example: If a Unit is moved to another Floor, all business logic that depends on its location must remain consistent. Any migration from inherited mall location logic must preserve existing data safely. 13. Stores Stores are one of the central entities in Mall. A store can include information such as: Name Description Category Zone Building Floor Unit Images Logo Contact information Visibility Other business information supported by the schema Exact fields must follow the current model/schema. 14. Store Visibility Stores have a visibility concept. Known inherited behavior: visibility = 1 represents the default visible state. A hidden/invisible store must not be treated as publicly discoverable where visibility applies. Visibility must be respected by relevant customer-facing API endpoints. 15. Top Stores Top-store functionality must respect store visibility. Known inherited rule: visibility = 1 is required for a store to appear in customer-facing top-store results. A store marked as top but hidden must not appear publicly. 16. Nearby / Location-Based Stores Mall may expose store discovery based on selected mall location. Where inherited location-based functionality is reused, the new Mall hierarchy must be considered. Location-based discovery may depend on: Zone Building Floor Unit A query must never return stores that do not belong to the intended location scope. Existing visibility and eligibility rules must continue to apply. 17. Favorite Stores Customers can mark stores as favorites. Favorite state is user-specific. Store resources may expose a field such as: is_favorite Favorite-store listing may use pagination. Known inherited behavior: 10 stores per page unless explicitly changed for Mall. Favorite state must never leak between users. 18. Store Category Filtering Stores can be discovered through categories. Category filtering must preserve all applicable restrictions such as: Location scope Store visibility Active state User eligibility Search/filter logic must not bypass visibility simply because a text/category match exists. 19. Categories Categories organize stores/products/content according to the implemented relationships. The Admin Dashboard may provide category filtering such as: All Active Hidden The API should only expose categories according to customer-facing visibility rules. Do not assume category active status and category visibility are always the same concept unless the schema confirms it. 20. Products Mall contains a product domain where supported by the inherited implementation. Products belong to the appropriate store/category relationships according to the current schema. Product behavior must follow: Store ownership Visibility Status Pricing Availability Category relationships Claude must inspect the current Product implementation before changing product business behavior. Do not invent: Inventory rules Stock management Pricing models Discount calculations unless explicitly required. 21. Bundles Mall may support bundles based on the inherited mall implementation. Before modifying bundle behavior, inspect: Bundle model Relationships Pricing rules Product relationships Availability API exposure Dashboard management No bundle calculation rule should be inferred without a requirement. 22. Offers Offers are promotional content associated with Mall and/or stores. Offers may be: Managed through Admin Dashboard Exposed through customer-facing APIs Offer visibility may depend on: Status Publication state Start date End date Store eligibility Location eligibility Existing fields Expired or unavailable offers must not be returned as active customer offers when date/status restrictions apply. Administrators may still need access to 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 the current implementation. 24. Banners Banners are promotional visual content managed by the dashboard and consumed by customer-facing clients. Banner behavior may depend on: Visibility Status Scheduling Placement Targeting Only eligible banners should be exposed to customer-facing clients. 25. Media Management Several modules may support image/media management, including: Stores Offers Events Banners Where image cropping already exists in the inherited project, the same behavior may be reused. Image updates must preserve the current 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. Inherited notification targeting may include: 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 inherited notification type mapping: 1 = Offers 2 = Stores 3 = Events These numeric values may already be used by existing records and clients. Do not change them casually. If notification types are refactored, backward compatibility must be considered. 28. Notification City Targeting Known inherited eligibility rule: 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 active customer notifications before becoming eligible. Known inherited filtering may include: scheduled != 1 where applicable. The scheduling flow must remain consistent with the current implementation. 30. Notification Read Tracking Notification read state is stored separately per user. Inherited read-tracking storage: app_notification_reads A notification being read by one customer must never mark it read for another customer. 31. Notification Read Feature Start Date Inherited historical compatibility rule: 2026-05-12 00:00:00 Notifications created before this date are treated as already read. created_at < 2026-05-12 00:00:00 → is_read = true This prevents old historical notifications from becoming unread when read tracking was introduced. 32. Notification Resource is_read Expected inherited behavior: 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: Current user Read feature start date User creation date City targeting Scheduling rules Existing notification eligibility rules Historical notifications must not incorrectly increase unread count. 34. Notification Ordering Read/unread state must not change natural notification ordering. Do not implement: Unread notifications first Read notifications second unless explicitly requested. Read and unread notifications should preserve the intended chronological/business ordering. 35. Scheduled Notification Ordering Scheduled notifications should be ordered according to the time they effectively become active/sent where applicable. Using only original created_at may create incorrect chronology when a notification was created earlier but scheduled for later. 36. Vouchers Mall may support vouchers based on inherited mall functionality. Known inherited voucher fields/defaults may include: approved = 1 added_type = mall Known values include: mall store When converting this behavior to Mall, old naming such as mall must be reviewed. Do not rename stored enum/database values without checking backward compatibility and existing data. 37. Payment Methods The inherited Admin Dashboard manages a predefined set of payment methods. Known current behavior: 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 include implementation-specific logic and integrations. Do not convert payment methods into fully dynamic records unless explicitly approved. 38. Quotations Mall may contain quotation-related functionality inherited from mall. 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 may contain order-related functionality. 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 is business-critical. Changes affecting: Amount Payment status Payment reference Order linkage Wallet Invoice Refund behavior require inspection of the full workflow. Do not make isolated changes to transaction calculations without tracing all consumers. 41. Invoices 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 should come from authoritative calculations rather than being independently recomputed in presentation code unless the architecture explicitly defines otherwise. 42. Wallet Mall may contain wallet-related functionality inherited from mall. Wallet changes are financially sensitive. Before changing wallet balances, 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. Before introducing a new hard-coded value, inspect whether an equivalent platform setting already exists. Do not move fixed business rules into settings unless configurability is explicitly required. 44. Localization Mall supports localized customer/admin content according to the inherited localization model. Expected languages include: Arabic English Localized entities may contain separate Arabic and English fields. 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 a language field because only one client currently displays it. 45. API Resource Rules Customer-facing API Resources should return only data needed by the client. Resources may include user-specific calculated fields such as: is_favorite is_read These values 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. Example inherited behavior: Favorite Stores → 10 per page Not every endpoint must use the same pagination size. Do not globally change pagination while fixing a single endpoint. 47. Status and Visibility Concepts Mall may contain multiple independent concepts: Active Inactive Visible Hidden Approved Pending Scheduled Expired Published Their meaning depends on the entity. Example: Store visibility is not automatically equivalent to: Store active status Claude must inspect each entity before reusing or merging status logic. 48. Public Visibility Principle Customer-facing APIs should generally return only content eligible for public/customer visibility. Eligibility may involve: active AND visible AND approved AND within valid date range AND matches targeting/location but the exact conditions differ by module. Do not blindly apply the same scope to every entity. 49. Admin Visibility Principle The Admin Dashboard may need access to data hidden from customers. Examples: Hidden stores Inactive categories Expired offers Scheduled notifications Archived records Pending content Customer-facing scopes must not accidentally be applied to Admin Dashboard queries unless intended. 50. Search and Discovery Mall search/discovery may involve filters such as: Store name Category Zone Building Floor Unit Other implemented filters Search logic must maintain all existing visibility and eligibility restrictions. A text match must never bypass business filters. 51. Dashboard Forms Admin forms must follow entity business requirements. Common responsibilities may include: Validation Arabic/English content Media upload Image crop Status Visibility Relationships Location hierarchy Scheduling where supported Edit forms must preserve existing values unless explicitly changed by the administrator. 52. 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. 53. Data Integrity Business relationships must remain valid. Examples: Zone → Building Building → Floor Floor → Unit Unit → Store Store → Category Offer → Store Notification → Target Order → Customer Financial record relationships Never bypass foreign-key or domain restrictions merely to make an operation succeed. 54. Financial Safety The following modules are financial or potentially financial: Orders Transactions Invoices Wallet Vouchers Payment methods Quotations where pricing is involved Before modifying a financial flow: Identify the authoritative amount source. Identify all dependent records. Identify status transitions. Identify API consumers. Identify dashboard consumers. Check historical data compatibility. Check duplicate/idempotency risks. 55. Backward Compatibility Mall inherits an existing mall codebase and may initially retain existing API consumers. Changes must consider backward compatibility for: Field names Enum/numeric values Resource structures Pagination Notification types Status values Existing client behavior Do not rename or remove an API field solely for internal code cleanliness. Breaking API changes require explicit approval. 56. API vs Dashboard Separation The same entity may behave differently depending on the consumer. Example: Store — Admin Dashboard May access: Visible Hidden Active Inactive Administrative metadata Full location hierarchy Store — Customer API Should return only stores eligible for customer exposure. Another example: Notification — Admin Dashboard Can manage: Configuration Targeting Scheduling Related offer/store/event Notification — Customer API Returns only notifications eligible for that specific user. This separation must be preserved. 57. Existing Behavior Preservation When implementing a task, Claude should preserve unrelated existing business behavior. Example: If the task is: Add Floor support to Unit management Claude should not simultaneously change: Favorite calculation Store visibility Notification ordering Pagination size API response structure unless required by the task. 58. No-Assumption Rule If Claude finds a 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 Form Request API Resource Livewire/Admin component Routes Tests Do not assume generic e-commerce behavior. 59. Mall-Specific Migration Rule from mall Because Mall is cloned from mall, inherited location-related code must be reviewed carefully. Any code that assumes: Building → Unit must be identified. Mall requires: Building → Floor → Unit Affected areas may include: Database migrations Eloquent relationships Form Requests Repositories Services Admin forms Dependent dropdowns API endpoints API Resources Filters Store registration Store assignment Search Reports Tests Seeders Factories Claude must not consider Floor support complete until all relevant consumers of Building/Unit relationships are reviewed. 60. Important Known Business Rules Summary Location Zone → Building → Floor → Unit → Store Stores Default visibility = 1 Hidden stores must not appear in customer-facing top-store results. Favorites Favorite state is per-user. Known inherited page size = 10. Categories Dashboard may include: All Active Hidden Notifications Known inherited types: 1 = Offers 2 = Stores 3 = Events City targeting: city_id IS NULL OR city_id = current_user.city_id Read feature start: 2026-05-12 00:00:00 Before this date: is_read = true Read/unread state must not change chronological ordering. Payment Methods Edit predefined payment methods = Supported Create arbitrary payment method = Not currently supported 61. Claude Working Checklist for Mall Before implementing any non-trivial Mall task, Claude should determine: Which business module is affected? Is this Admin, API, or both? Who is the actor? Is the behavior inherited from mall or Mall-specific? Does the task affect the new Floor hierarchy? What existing business rule applies? What API behavior must remain compatible? What related entities can be affected? Is there user-specific state? Is there visibility/status/date filtering? Is there financial impact? What tests prove the intended behavior? The task should then be implemented with the smallest safe scope. 62. Core Principle The central rule when maintaining Mall is: Understand the Mall business flow first, then modify the inherited implementation. The mall codebase is a starting point, not the final business specification. All changes must preserve: Data integrity Customer isolation Store isolation Admin authorization API compatibility Location hierarchy integrity Visibility rules Localization Financial correctness Existing unrelated functionality