Org::OutletAssignment

Purpose

An Org::OutletAssignment links an Org::Membership to a specific Org::Outlet, defining which outlets a user can access and manage. It is the mechanism that scopes area_manager and outlet_manager roles to specific outlets within a company.

In the workforce management domain, this is commonly called a "location assignment" — it answers: "Where does this person work?"

hq_manager memberships do not need outlet assignments — they have implicit access to all outlets in their company. Only area_manager and outlet_manager memberships require explicit assignments.

Key Concepts

Direct Assignment, Not Persistent Groups

Outlet assignments are a direct link between a membership and an outlet. There is no intermediate "area" or "zone" entity. If the company reorganizes which outlets each manager oversees, the assignments are updated directly.

This design was informed by data analysis of the legacy system (JodGig), where AREA managers managed 1–10 outlets each, and assignments were made by linking the user directly to locations via locations.area_user_id. No formal "area group" existed. See JodGig Org Statistics for details.

Assignment Rules by Role

Role	Required Assignments	Meaning
hq_manager	None (zero assignments)	Implicit access to all outlets in the company
area_manager	1 or more outlets	Can manage jobs, candidates, and shifts at assigned outlets only
outlet_manager	Exactly 1 outlet	Can manage jobs, candidates, and shifts at their single outlet only

Multiple Managers per Outlet

Multiple memberships can be assigned to the same outlet. For example, one outlet might have:

• 1 outlet_manager (the primary manager)
• 1 area_manager who also covers this outlet along with several others

This matches the legacy system, where data showed some outlets had up to 8 LOCATION managers assigned to the same location.

Model Context

Context	Details
Entity	Org::OutletAssignment (child of Org::Membership aggregate)
Layer	Organisation Structure — Access Scoping
Upstream dependencies	Org::Membership (the user's access grant), Org::Outlet (the physical branch)
Downstream dependents	Gig::Job and Careers::Job (scoping determines which jobs a user can see and manage)

Use Cases

ID	Use Case	Trigger	Actor
UC-1	Assign outlets to a membership	New member needs scoped access	hq_manager or Admin
UC-2	Add an outlet to an existing assignment	Manager takes on additional outlet	hq_manager or Admin
UC-3	Remove an outlet from an assignment	Manager no longer oversees this outlet	hq_manager or Admin
UC-4	Reassign all outlets (bulk update)	Company reorganizes manager responsibilities	hq_manager or Admin
UC-5	View outlet assignments for a membership	hq_manager reviews who manages which outlets	hq_manager

---

UC-1: Assign outlets to a membership

Field	Details
Actor	hq_manager of the company, or Identities::Admin
Trigger	New member with area_manager or outlet_manager role needs outlet access

Preconditions:

• Membership exists with role area_manager or outlet_manager
• Membership has no existing outlet assignments
• Target outlets belong to the same company as the membership

System Behavior:

1. Actor selects one or more outlets to assign
2. System creates Org::OutletAssignment records linking the membership to each outlet
3. For outlet_manager: system validates exactly 1 outlet is assigned

Business Rules:

• Outlets must belong to the same Org::Company as the membership — no cross-company assignments
• outlet_manager must be assigned exactly 1 outlet
• area_manager must be assigned at least 1 outlet
• hq_manager memberships cannot have outlet assignments (they have implicit full access)
• Multiple memberships can be assigned to the same outlet
• Only active outlets can be assigned (inactive outlets are excluded)

Postconditions:

• OutletAssignment records exist
• The user can now see and manage jobs at the assigned outlets

---

UC-2: Add an outlet to an existing assignment

Field	Details
Actor	hq_manager of the company, or Identities::Admin
Trigger	Manager takes on additional outlet responsibility

Preconditions:

• Membership exists with role area_manager
• Target outlet belongs to the same company
• Target outlet is not already assigned to this membership

System Behavior:

1. Actor selects an additional outlet
2. System creates a new Org::OutletAssignment record

Business Rules:

• Only area_manager can have outlets added (they manage multiple outlets)
• outlet_manager cannot have outlets added — they are limited to exactly 1. To change their outlet, use UC-3 + UC-1 (remove old, assign new).
• No duplicate assignments: a membership cannot be assigned to the same outlet twice

Postconditions:

• New OutletAssignment record exists
• The user can now see and manage jobs at the additional outlet

---

UC-3: Remove an outlet from an assignment

Field	Details
Actor	hq_manager of the company, or Identities::Admin
Trigger	Manager no longer oversees this outlet

Preconditions:

• OutletAssignment exists for the given membership and outlet

System Behavior:

1. Actor removes the outlet assignment
2. System deletes the Org::OutletAssignment record

Business Rules:

• After removal, area_manager must still have at least 1 outlet assigned. If removing the last outlet, the system should warn the actor — the membership would have no outlet access.
• For outlet_manager, removing their only outlet means they have no access. The actor should either assign a new outlet or change the membership's role.
• Removing an assignment does not affect active jobs or shifts at that outlet — the user simply loses the ability to create new jobs or manage future work there.

Postconditions:

• OutletAssignment record removed
• The user can no longer see or manage new jobs at that outlet

---

UC-4: Reassign all outlets (bulk update)

Field	Details
Actor	hq_manager of the company, or Identities::Admin
Trigger	Company reorganizes manager responsibilities

Preconditions:

• Membership exists with role area_manager or outlet_manager

System Behavior:

1. Actor provides the new set of outlet IDs for the membership
2. System replaces all existing outlet assignments with the new set
3. Assignments not in the new set are removed; new outlets are added

Business Rules:

• Same validation rules apply: outlet_manager gets exactly 1, area_manager gets 1 or more
• All outlets must belong to the same company as the membership
• This is a convenience operation — equivalent to removing all and re-adding, but atomic

Postconditions:

• OutletAssignment records match the new set exactly
• The user's outlet access is updated immediately

---

UC-5: View outlet assignments for a membership

Field	Details
Actor	hq_manager of the company
Trigger	hq_manager reviews who manages which outlets

Preconditions:

• Actor has hq_manager role in the company

System Behavior:

1. System displays each membership and its assigned outlets
2. For hq_manager memberships: shows "All outlets (implicit)"
3. For area_manager and outlet_manager: shows the list of assigned outlets

Postconditions:

• Read-only operation — no data changes

---

Invariants

1. An Org::OutletAssignment links exactly one Org::Membership to exactly one Org::Outlet
2. The outlet must belong to the same Org::Company as the membership — no cross-company assignments
3. outlet_manager memberships must have exactly 1 outlet assignment
4. area_manager memberships must have at least 1 outlet assignment
5. hq_manager memberships must have zero outlet assignments — their access to all outlets is implicit
6. A membership cannot be assigned to the same outlet twice (unique constraint on membership_id + outlet_id)
7. Multiple memberships can be assigned to the same outlet (e.g., one outlet_manager and one area_manager at the same outlet)
8. Only active outlets can be assigned — inactive outlets cannot receive new assignments
9. Outlet assignments are soft-deleted when the membership is revoked (revoked_at is set) — this preserves the audit trail of which outlets a user managed before they left. Soft-deleted assignments are excluded from active queries.

Model Interactions

Related Model	Relationship	Interaction
Org::Membership	Assignment belongs_to Membership	The user's access grant to a company. Assignments scope the membership to specific outlets.
Org::Outlet	Assignment belongs_to Outlet	The physical branch. One outlet can have multiple assignments from different memberships.
Org::Company	(indirect, via Membership and Outlet)	Both the membership and the outlet must belong to the same company. Enforced at creation time.
Gig::Job	(indirect, via Outlet)	Outlet assignments determine which gig jobs a scoped user can see and manage.
Careers::Job	(indirect, via Outlet)	Outlet assignments determine which career jobs a scoped user can see and manage.
Org::Invite	Invitation can pre-specify outlets	When inviting a user, the inviter can specify which outlets to assign on acceptance.

Schema Gaps

Gap	Impact	Suggested Resolution
No org_outlet_assignments table exists	Cannot scope memberships to specific outlets	Resolved in DBML. org_outlet_assignments table defined with membership_id (FK), outlet_id (FK), revoked_at, created_at, updated_at. Unique index on (membership_id, outlet_id).