Marketplace Caterer User Management Models

This document outlines the data models related to the management of restaurant partners (users) on CaterCow. The models are designed to provide a flexible and hierarchical structure for managing restaurant operations, permissions, and resources.

Restaurant Partner Hierarchy

The core of the user management system is a three-tiered (plus one) hierarchical model that represents the structure of the food providers.

• RestaurantGroup: This is the highest-level entity, representing a parent company or an ownership group that may own and operate multiple distinct restaurant brands.
• Brand: A Brand is a specific restaurant concept or chain that belongs to a RestaurantGroup. For example, a restaurant group named "Gourmet International" might own brands like "Speedy Tacos" and "Artisan Pizza." Each brand has its own identity, menu, and operational characteristics. For more on menu structure, see Menus.
• Kitchen: This model represents the physical, brick-and-mortar locations where the food is prepared. A single Brand can operate out of one or more Kitchens. Each kitchen has a physical address and its own operational settings, such as business hours and delivery zones.

Most users and records fall neatly somewhere along this hierarchy; however, a fourth layer can be applied for restaurants that need it:

KitchenGroup: This is a flexible grouping model that allows for the logical association of Kitchens. Its primary uses are:

• Franchise Management: A franchise owner might own several kitchens that fall under the same brand or even across different brands within a restaurant group. A KitchenGroup can be created to grant this owner access and control only over the kitchens they own.
• Manual Order Routing: Kitchen groups can be used to define delivery zones that are not automatically assigned to a single kitchen. When a customer places an order in such a zone, it is sent to the kitchen group, and a user with dispatch permissions can then route the order to the most appropriate kitchen within that group.

Scoped Permissions, Contacts, and Entities

User access, notifications, and other key entities are managed through a set of models that can be applied at any level of the hierarchy described above (RestaurantGroup, Brand, KitchenGroup, or Kitchen). This allows for highly granular control.

The scoping mechanism is hierarchical. A record defined at a higher level applies to all entities beneath it. For example, a role assigned at the RestaurantGroup level will have its brand_id, kitchen_group_id, and kitchen_id fields set to NULL and will grant permissions across all entities within that group. A kitchen-level record would have all relevant foreign keys populated.

• CatererRole: This model defines a user's permissions. It links a User to a specific entity and assigns them a role_type. While roles and contact preferences can be customized, CaterCow provides several presets:
  • Admin: Full access to every aspect of the business.
  • Manager: Full access to business operations but cannot change financial information like bank accounts.
  • Finance: Can view most business information and can edit financial and legal data.
  • Employee: Can view business information (orders, etc.) but cannot make changes.
• CatererContact: This model defines a user's notification preferences for events related to orders, financials, and messages. Like roles, these can be set and stacked at any level of the hierarchy, and while presets exist, each notification type can be toggled for a custom configuration.
• LegalEntity: This model represents a financial entity and maps directly to a Stripe Connect account. It is used for processing payments and managing payouts. Beneath each LegalEntity are its associated BankAccounts. Scoping a legal entity allows for distinct financial management at the group, brand, or even individual kitchen level.
• SimpleContact: Represents a point of contact, which can be a person, a physical storefront, or another entity that may or may not have a user account on the platform. These are primarily utilized by internal operations teams and can be surfaced to customers on a specific order if relevant for delivery or coordination.

User Invitation Flow

Access to manage restaurant entities is granted through a formal invitation process.

• CatererInvitation: When an administrator wants to grant a new user access, they create a CatererInvitation. This record links an email address to one or more CatererRoles at a specific scope.
• Invitation Email: An email is sent to the invited user containing a unique, tokenized link.
• Claiming Access: When the user clicks the link, they can claim the invitation. If they do not have an account, they will be prompted to sign up. Once the invitation is claimed, the associated roles and contact preferences are applied to their user account, granting them the appropriate access.

Brand and Kitchen Level Resources

While some models are scoped globally, many operational resources are managed primarily at the Brand and Kitchen levels.

Model Name	Level(s)	Description
Package	Brand	Pre-defined meal bundles or catering packages offered by a Brand.
Coupon	Brand	Promotional codes and discounts that can be applied to orders for a specific Brand.
AvailabilityDate	Kitchen	Allows setting specific dates where a Kitchen or entire Brand is available or unavailable, overriding regular BusinessHours.
BusinessHour	Kitchen	Defines the standard weekly operating hours for a Kitchen or for all kitchens under a Brand.
KitchenDeliveryArea	Kitchen / Kitchen Group	Links a specific Kitchen to a delivery zone, defining the delivery fee, minimum order amount, and other logistics for that zone from that kitchen. If set to manual assign, there must be a KitchenGroup attached
Order	Brand / Kitchen	Represents a customer order. It is linked to the Brand from which the items were ordered and the specific Kitchen that will fulfill it.
Payout	Brand	Manages the financial payouts to the restaurant partner for the orders they have fulfilled. Tied to a LegalEntity.
CatererDocument	Brand	Stores private/legal documents such as 1099-K tax forms.

Payout Flow

The process for paying catering partners for their fulfilled orders involves several connected models to ensure funds are routed correctly.

1. An Order is fulfilled by a specific Kitchen. The revenue from this order is attributed to that Kitchen.
2. Each Kitchen must be assigned a single BankAccount to receive funds.
3. Each BankAccount, in turn, is owned by a LegalEntity (a Stripe Connect Account).
4. A Payout is then generated and sent to the BankAccount associated with the LegalEntity that owns the fulfilling Kitchen.

This structure ensures a clear financial trail. The scoping is strict: if a LegalEntity is scoped to a specific Brand or KitchenGroup, its BankAccounts can only be assigned to Kitchens that also fall under that same scope. This prevents funds from being routed to an incorrect part of a restaurant's organization and it is particularly important when there are multiple owners involved.