full-stack engineering · python · api
Building a Multi-Role Restaurant System | RBAC & Architecture
Building restaurant software involves more than managing orders. In this article, I explore the architecture behind a multi-role restaurant operations system, including role-based access control, order lifecycles, multi-tenancy, inventory consistency, and the engineering decisions involved in designing reliable business workflows.

Building a Multi-Role Restaurant Operations System: Architecture, RBAC, and Workflows
Category: Full-Stack Engineering
Topics: System Design, FastAPI, PostgreSQL, Next.js, RBAC, Multi-Tenancy, Domain Modeling
Article type: Engineering Case Study
Status: Development in progress ---- architecture and implementation details subject to repository verification

Building a restaurant management application sounds straightforward until you examine what happens behind the counter.
A waiter takes an order. The kitchen prepares it. Inventory changes as ingredients are consumed. A cashier processes payment. A manager monitors operations, while the restaurant owner needs visibility into the entire business.
These aren't simply independent CRUD operations. They're connected workflows involving different actors, business rules, permissions, and shared data.
An order that appears on a waiter's screen may simultaneously affect kitchen operations, inventory, payment processing, and financial reporting.
This creates an interesting engineering challenge:
How do you design a full-stack system where multiple employees can perform different operations on shared business resources without compromising authorization, consistency, or operational correctness?
That's the problem I'm exploring through my Restaurant Operations System.
The project is designed as a multi-role business operations platform, bringing restaurant workflows into one application while providing an opportunity to explore production-oriented software architecture.
In this article, I'll explain the system's domain, the architecture we've been developing, our approach to role-based access control, and the engineering decisions involved.
I'll also distinguish the architecture's intended behavior from features that still require implementation verification.
1. Understanding the problem
Many restaurant operations involve several activities happening concurrently.
Consider a typical service period:
A waiter creates an order for a table.
The kitchen receives the order.
A chef begins preparing the food.
Inventory must reflect the appropriate stock movements.
The kitchen marks the order as ready.
The waiter serves the customer.
Payment is recorded.
Management reviews the day's activity.
Each step involves different responsibilities.
A waiter shouldn't automatically have access to financial administration. Kitchen staff shouldn't need permission to manage employee accounts. An inventory manager may need to record stock movements without having access to billing configuration.
The system therefore needs more than authentication.
It needs an understanding of who is performing an action, which resource they're operating on, and whether that action is permitted within the current business context.
There are also several data-consistency questions:
What happens if two employees update the same order?
Can an order be moved to an invalid status?
What happens when a payment callback is delivered twice?
How should inventory changes be recorded?
How can staff permissions be restricted to a restaurant or branch?
What happens if part of a business operation succeeds and another part fails?
These questions have influenced the architecture of the system.
2. Defining the system's actors
One of the first architecture exercises was identifying the different people and external systems involved.
We identified six principal internal roles.
Role | Responsibility |
|---|---|
Owner | Restaurant-level configuration and oversight |
Manager | Supervising restaurant operations and staff |
Waiter | Creating, updating, and managing customer orders |
Kitchen Staff | Viewing assigned kitchen orders and updating preparation progress |
Inventory Manager | Monitoring stock and recording inventory movements |
Accountant | Financial records, reconciliation, and reporting |
We also identified external actors:
Customers: People purchasing meals or services from the restaurant.
Payment providers: External services responsible for payment processing and notifications.
Messaging providers: Services that may support operational notifications.
These actors help define the system's boundaries.
For example, the customer does not necessarily need an internal staff account, while a payment provider interacts through an integration rather than through a restaurant employee's permissions.
This distinction makes it easier to design authentication, authorization, and business workflows independently.
3. Choosing the architecture
The initial architectural direction is a modular monolith.
Rather than introducing independent microservices for orders, inventory, payments, and staff management, the application is organized around distinct business modules within a shared backend.
A modular monolith provides a useful balance between simplicity and separation of concerns.
It allows the system to maintain explicit boundaries between business domains without immediately introducing distributed deployment, cross-service communication, and additional operational complexity.
Planned technology stack
The technical stack we selected during planning includes:
Layer | Technology |
|---|---|
Frontend | Next.js, React, TypeScript |
UI | Tailwind CSS and shadcn/ui |
Backend | Python and FastAPI |
Database | PostgreSQL |
ORM | SQLAlchemy |
Migrations | Alembic |
Background processing | Redis with Celery or Arq, subject to implementation |
Authentication | JWT or secure session cookies, based on final design |
Testing | pytest, Playwright, k6 |
Development infrastructure | Docker |
Observability | Structured logging and OpenTelemetry as an architectural objective |
This table documents the planned stack, not an assertion that every component has already been integrated.
Logical architecture
The proposed request flow is:
Users
|
v
Next.js Application
|
| HTTPS / API Requests
v
FastAPI Backend
|
+-- Authentication & Authorization
|
+-- Organization / Branch Management
|
+-- Staff Management
|
+-- Menu Management
|
+-- Orders
|
+-- Kitchen Operations
|
+-- Inventory
|
+-- Payments
|
+-- Reporting
|
v
PostgreSQLBackground workers and external services can be integrated around these modules as their requirements become concrete.
The important decision is to separate business responsibilities logically without requiring every module to be an independently deployed service.
4. Designing the multi-tenant model
Multi-tenancy is another significant part of the project's architecture.
Instead of modeling an application that belongs permanently to one restaurant, the design considers a structure where multiple restaurant businesses can use the same platform.
Each organization represents a tenant.
An organization may operate one or more restaurant branches.
A conceptual hierarchy looks like this:
Organization
|
+-- Branch A
| |
| +-- Staff
| +-- Tables
| +-- Orders
| +-- Inventory
|
+-- Branch B
|
+-- Staff
+-- Tables
+-- Orders
+-- InventoryThe organization defines the business boundary, while the branch defines an operational boundary.
This introduces an important requirement: a user who has access to one organization or branch must not automatically gain access to another.
For example, a manager assigned to Branch A should not be able to retrieve Branch B's operational records merely by changing an identifier in an API request.
Tenant isolation must be enforced at the backend and persistence boundaries.
Why this matters
A multi-tenant system needs to answer several questions consistently:
Which organization owns this resource?
Which organization is the user operating within?
Does the user belong to that organization?
Which branches can they access?
Does their assigned role authorize the requested operation?
These decisions must not depend solely on values supplied by the frontend.
A request containing an organization_id is not proof that the requester belongs to that organization.
That relationship must be verified independently.
5. Role-Based Access Control: Roles are not enough
One of the most important areas of the design is authorization.
At first, it's tempting to place a role field directly on the user model:
class UserRole(str, Enum):
OWNER = "owner"
MANAGER = "manager"
WAITER = "waiter"
KITCHEN = "kitchen"
INVENTORY_MANAGER = "inventory_manager"
ACCOUNTANT = "accountant"For a small application, this can be a reasonable starting point.
However, multi-tenancy introduces a complication.
A user may belong to multiple organizations, potentially with different responsibilities.
For example, the same person could be a manager in one organization and a waiter in another.
This makes a single global user role insufficient for the longer-term design.
The authorization model
The direction we're exploring is:
User
|
v
Organization Membership
|
v
Assigned Role
|
v
Permissions
|
v
Resource Scope
|
v
Authorization DecisionThis separates identity from organizational membership and access rights.
The user answers who you are.
The membership answers which business you belong to.
The role and permissions answer what you're allowed to do.
The resource scope answers where you're allowed to do it.
Example permission matrix
The following matrix is illustrative and remains subject to the finalized authorization rules.
Operation | Owner | Manager | Waiter | Kitchen |
|---|---|---|---|---|
Manage staff | Yes | Limited | No | No |
Create orders | Yes | Yes | Yes | No |
Update preparation status | Yes | Yes | No | Yes |
Configure restaurant | Yes | Limited | No | No |
View operational reports | Yes | Yes | Limited | No |
The critical implementation principle is that permissions must be enforced on the server.
Hiding a button from an unauthorized user improves the interface, but it doesn't secure an API endpoint.
Every protected operation should validate the authenticated user's membership, permission, and resource scope.
6. Modeling the order lifecycle
The order management workflow is one of the central domains.
A waiter creates an order and submits it to the kitchen. Kitchen staff prepare the order and mark it as ready. The waiter then handles the next stages of service.
During our domain modeling discussions, we established that kitchen staff should not be responsible for the entire order lifecycle.
Their responsibility ends when the order is ready.
This is a useful example of how business responsibilities influence software design.
Conceptual order states
Draft
|
v
Submitted
|
v
Preparing
|
v
Ready
|
v
Served
|
v
CompletedThis is an illustrative lifecycle. The actual state machine must also account for cancellation, exceptional conditions, and payment policy.
An important design objective is to prevent arbitrary state changes.
For example, an order shouldn't move from Draft directly to Served unless an explicit business rule permits it.
Similarly, not every role should be allowed to perform every transition.
A well-defined order state machine provides a way to enforce these rules consistently.
Domain transitions versus direct updates
A conventional CRUD implementation might allow a client to update an arbitrary status:
PATCH /orders/123
Content-Type: application/json
{
"status": "completed"
}That interface can become dangerous if the backend accepts every requested transition without validation.
A more explicit domain-oriented approach is to model meaningful business actions:
CreateOrder
SubmitOrder
StartPreparation
MarkOrderReady
MarkOrderServed
CompleteOrder
CancelOrderEach action can validate the current state, the actor's permissions, and the relevant business invariants.
The objective is to make invalid operations difficult to express and straightforward to reject.
7. Concurrency and consistency
Restaurant systems can encounter concurrent updates even when the number of users is relatively small.
Consider two staff members attempting to modify the same order.
Without a concurrency strategy, one employee's changes could silently overwrite another's.
Depending on the operation, possible approaches include:
Optimistic concurrency using version numbers.
Database transactions.
Row-level locking.
Conditional updates based on the current state.
These mechanisms solve different problems and should be selected based on the actual workflow.
Example: Conditional status transition
An illustrative SQL pattern is:
UPDATE orders
SET
status = 'preparing',
version = version + 1
WHERE id = :order_id
AND organization_id = :organization_id
AND status = 'submitted'
AND version = :expected_version
RETURNING id, status, version;If no row is returned, the application must determine whether the order was not found, the requester lacked the appropriate scope, or the state/version no longer matched the expected value.
Authorization should already have been established before attempting the mutation.
The broader principle is that business rules must remain valid under concurrent execution, not just during sequential testing.
8. Inventory as a transactional domain
Inventory management introduces another set of consistency problems.
An inventory system must represent the movement of resources over time.
For the Restaurant Operations System, the planned inventory domain includes movements related to:
Purchases.
Ingredient usage.
Waste.
Stock transfers.
Adjustments.
Rather than treating the inventory balance as an isolated number, the design considers recording stock movements as explicit transactions.
For example:
Ingredient: Rice
Purchase +50 kg
Kitchen Usage -12 kg
Waste -2 kg
------------------------
Recorded Balance 36 kgThis creates a traceable history of why stock changed.
Why an inventory ledger is useful
If a balance changes from 50 kg to 36 kg, an audit trail can explain the difference.
This is especially important when multiple employees are responsible for purchases, kitchen operations, and stock adjustments.
However, a ledger alone doesn't guarantee correctness.
The system must also consider:
Duplicate movement requests.
Concurrent deductions.
Incorrect measurement units.
Inventory corrections.
Reversals.
Atomic recording of related operations.
These are engineering requirements to validate through implementation and testing.
9. Payments and external integrations
Payments are another area where application state and external systems interact.
A payment provider may report an outcome asynchronously through a webhook.
This creates several reliability questions.
What happens if a webhook arrives twice?
What happens if the application receives a callback after a temporary outage?
What happens if the payment provider confirms a payment but the local database update fails?
These problems motivate the use of:
Verified webhook signatures.
Unique transaction references.
Idempotent processing.
Persistent payment records.
Transactional state changes.
Reconciliation procedures.
The implementation must reflect the specific payment provider's documented behavior.
At the current stage, these should be treated as intended integration and reliability requirements rather than claims that a complete payment-processing workflow has been implemented.
10. Frontend engineering: Interfaces built around responsibilities
Because this is a full-stack project, frontend architecture is just as important as backend design.
Different users need different operational interfaces.
A waiter needs an efficient order-entry workflow.
Kitchen staff need visibility into the preparation queue.
An inventory manager needs stock records and movement history.
A manager needs operational visibility and administrative controls.
Instead of building one enormous dashboard where every user sees every feature, the design calls for role-aware navigation and interfaces organized around actual responsibilities.
For example:
Restaurant Application
|
+-- Owner / Management
| +-- Overview
| +-- Staff
| +-- Settings
| +-- Reports
|
+-- Waiter
| +-- Tables
| +-- Orders
|
+-- Kitchen
| +-- Preparation Queue
|
+-- Inventory
+-- Stock
+-- Movements
+-- PurchasingThis is a proposed navigation structure, not a verified inventory of existing pages.
The frontend should use authorization information to guide navigation and user experience.
However, the backend remains responsible for enforcing permissions.
A user being unable to see an action in the interface must never be the application's only access-control mechanism.
11. Billing and organizational access
As the architecture evolved, we also began considering organization-level billing and the integration of authentication, permissions, and subscriptions.
This raises another important distinction.
Billing entitlement is not the same thing as authorization.
A user might have permission to manage staff within an organization, but the organization's subscription might not include a particular feature.
Conversely, an organization might have access to a paid feature, but a waiter shouldn't automatically gain permission to configure it.
Conceptually, a protected operation may need to satisfy both conditions:
Authenticated User
|
v
Valid Organization Membership
|
v
Required Permission
|
v
Applicable Resource Scope
|
v
Organization Feature Entitlement
|
v
Allow or Reject OperationThis separation helps keep staff permissions independent from product pricing and subscription logic.
The concrete billing implementation and enforcement mechanism remain details to verify against the current codebase.
12. Testing strategy
The testing strategy needs to validate business behavior, not simply whether endpoints return successful responses.
For authorization, important scenarios include:
A waiter attempting an administrative operation.
A user requesting resources from another organization.
A manager attempting an action outside their assigned branch.
A user whose membership has been revoked.
A role change occurring while a session remains active.
For orders:
Valid state transitions.
Invalid transitions.
Concurrent updates.
Duplicate submission attempts.
Cancellation and recovery paths.
For inventory:
Insufficient stock.
Duplicate stock movements.
Concurrent deductions.
Invalid quantities.
Transaction rollback.
Consistent balances after failures.
For payments:
Duplicate webhooks.
Invalid signatures.
Delayed callbacks.
Provider timeouts.
Reconciliation after partial failures.
The planned testing tools include pytest for backend tests, Playwright for end-to-end testing, and k6 for performance testing.
These are testing objectives. Published results, coverage statistics, or load-test numbers should only be added once they have actually been measured.
13. Engineering trade-offs
Several design decisions stand out from this project.
Modular monolith versus microservices
Starting with a modular monolith reduces deployment and operational complexity while still encouraging explicit business boundaries.
It doesn't eliminate the need for good module design, but it avoids introducing distributed systems problems before independent services are justified.
Global roles versus organization-scoped permissions
A single global user role is easier to implement initially.
Organization-scoped memberships and permissions are more flexible for a multi-tenant product, but they require more careful modeling and authorization checks.
CRUD endpoints versus domain operations
Generic CRUD endpoints can accelerate simple administrative features.
For important business workflows, explicit domain operations make state transitions and authorization rules easier to reason about.
Mutable inventory balances versus movement history
Maintaining a current balance is convenient for queries.
Recording stock movements provides a stronger audit trail, but requires careful handling of corrections, concurrency, and consistency.
A practical design may maintain both movement records and a derived or transactionally maintained balance.
14. Current progress and remaining work
The project has progressed through substantial domain and architecture discussions.
The established design work includes:
Identifying the principal business actors.
Defining the responsibilities of restaurant staff.
Exploring a modular-monolith architecture.
Selecting an initial full-stack technology direction.
Modeling organizations and branches.
Designing an organization-scoped RBAC approach.
Defining the core order workflow.
Establishing kitchen and waiter responsibility boundaries.
Exploring inventory movement and transactional consistency.
Identifying the need for payments, billing, and integration boundaries.
Defining important concurrency and testing scenarios.
The repository implementation needs to be inspected before reporting individual modules as completed, tested, deployed, or production-ready.
The next technical milestones are to establish the implemented database schema, verify server-side authorization, validate order transitions, test concurrency-sensitive workflows, and document the actual integration behavior.
15. What this project is teaching me
One important lesson from designing this system is that building business software requires more than creating endpoints and connecting them to user interfaces.
You have to understand the domain.
A role is more than a string stored in a database.
An order status is more than a field that can be updated.
An inventory balance is more than a number.
A payment confirmation is more than a successful HTTP response.
Each represents business rules, state transitions, trust boundaries, and failure conditions.
The challenge is translating those requirements into software that behaves correctly, including when operations happen concurrently or external dependencies fail.
For me, that's where full-stack engineering becomes particularly interesting: understanding the complete path from a user's action in the interface to the rules, persistence, and infrastructure that make the operation reliable.
Conclusion
The Restaurant Operations System is an ongoing exploration of what it takes to build a multi-role, potentially multi-tenant business application.
The central engineering challenges involve authorization, workflow modeling, transactional consistency, and coordinating activities across different business domains.
The architectural direction favors a modular monolith, organization-scoped permissions, explicit domain operations, and careful handling of state changes.
As implementation progresses, these designs need to be evaluated against actual code, tests, and operational behavior.
The goal isn't simply to produce a functional restaurant dashboard.
It's to build a system whose behavior can be explained, verified, and maintained as its complexity increases.
The most valuable part of this project is learning to connect business rules with concrete engineering decisions across the entire stack.
This article documents the project's architecture and development direction. Implementation-specific details and measured results will be updated following repository verification.