Ropa & Organizational Unit

Source: src/models/ropa.ts

Each Organization has one Ropa document per configured locale, referenced via Organization.ropas[].ropaId. The Ropa document is the container for all Organizational Units and their activities for that locale.

Ropa

One Ropa document = one org × one locale.

Field	Type	Required	Notes
orgId	String	—	Organization._id cast to string; used for scoped queries.
orgShortName	String	✓	2–32 chars; denormalized copy of Organization.shortName for cache key construction.
locale	String	✓	2-letter lowercase code, e.g. "es". Matches /^[a-z]{2}$/.
ous	OU[]	—	All organizational units for this locale, each containing activities.
createdAt / updatedAt	Date	—	Managed by timestamps: true.

Indexes

Index	Type	Notes
{ orgId: 1 }	Normal	Primary lookup by organization.
{ "ous.activities.activityId": 1 }	Sparse	Fast activity lookup across all OUs without scanning the full document.

---

Organizational Unit (OU)

Nested inside Ropa.ous[].

Field	Type	Required	Notes
ouId	Number	✓	Unique per Ropa; assigned from Organization.highestOuId.
ouName	String	✓	Display name.
ouColor	String	—	Hex color used in the UI to visually distinguish OUs.
templateId	ObjectId	—	Optional reference to a Template document. When set, overrides the org-level template fallback for all activities in this OU that do not have their own templateId.
activities	Activity[]	—	See Activity.

---

Document structure

Ropa
└── ous[]
    ├── ouId, ouName, ouColor, templateId
    └── activities[]
        ├── activityId, activityName, ...
        └── templateId  (activity-specific override)

To find an activity:

1. Fetch Organization by shortName → get ropaId from ropas[] matching the target locale.
2. Fetch Ropa by _id.
3. Iterate ous[].activities[] to find the entry matching activityId.

The sparse index on { "ous.activities.activityId": 1 } supports step 3 at the database level when querying via aggregation or $elemMatch.