Defining hierarchy levels

Before you can add a single unit, GCM needs to know what to call it. A unit on level 2 might be a Center in one church, a Campus in another, a Region in a third. The labels are entirely yours.

This page is purely about labels and on/off toggles. Actually creating units happens in Creating units.

Open the hierarchy editor

Go to Settings → Org Hierarchy in the sidebar. You'll land on the HierarchyTab panel with one card per defined level.

A fresh organization starts with level 1 already in place — named Branch by default — because the model requires at least one level for the rest of the app to work. Levels 2 through 10 are added on demand.

Each level has four fields

Field	What it controls	Required?
Singular label	What one unit is called ("Branch", "Center")	Yes
Plural label	What many units are called ("Branches", "Centers") — used in page titles, table headers	No, defaults to label + "s"
Enabled	Whether this tier appears in unit-creation menus and filters	Yes for level 1, optional below
Level index	The numeric tier (1 = top). Set automatically — you can't reorder mid-edit	n/a

The singular label feeds buttons like Add Branch, the create-unit dialog title, and every place the UI mentions the tier in body copy. The plural shows up on stat cards ("3 branches with 482 members") and in the page header. Both are translated through the t() function if you've enabled Spanish.

Add a level

Click Add level N+1 at the bottom. GCM seeds the new level with a placeholder label ("Level 4") and a placeholder plural ("Level 4s"). Open the card, type your real names, click Save changes.

Levels can be added up to a hard cap of 10. Past that the button disappears.

Don't reorder after you've created units

The level index is the foreign key from org_units.level_index back to org_level_definitions.level_index. Renumbering a level after you've created units would orphan them. The UI doesn't let you reorder for that reason — plan two levels deeper than you need today so you have headroom.

Toggle a level off

If you set up Region → Branch → Center → Cell but later collapse to Branch → Cell, you can flip the Enabled switch on Region and Center off. Disabled levels:

• Disappear from the create-unit menu.
• Are hidden from the org-tree drill-down.
• Are skipped in unit pickers throughout the app.
• Keep their existing rows in org_units — the data isn't deleted, just hidden.

Level 1 cannot be disabled. The switch is hidden on that card because the rest of the module assumes at least one tier exists.

Remove a level

Levels can only be removed when they're the last one in the sequence and have no units attached. The trash icon shows up beside the level title in two specific cases:

1. The level is the highest defined level (you can't punch a hole in the middle of the hierarchy).
2. Zero units exist at that level.

If either condition fails, the button hides — you'll need to delete or move the existing units first. See Archive + restore for cleanup.

Common patterns by church type

Church type	Suggested levels
Single site, small	Just Ministries — one level, named whatever your members say
Single site, large	Department → Ministry
Two-site	Branch → Ministry
Cell-based	Branch → Center → Cell
Denominational	Region → District → Local Church
Megachurch with campuses	Region → Campus → Department → Small Group

The right number is the smallest number that lets your reports cascade and your shepherds narrow to their slice. Adding levels you'll "grow into" usually means empty boxes in your dashboard.

What the count badges mean

Each level card shows two badges beside the title once units exist:

• N units — how many active units sit at this level. Counts exclude archived rows.
• L of N leaders — how many of those units have a leader_member_id set. The gap is the to-do list: unstaffed branches, cells without shepherds, etc.

These badges are a quick health check. If level 3 says "12 units, 2 leaders" you have ten unstaffed groups — probably the reason your follow-up reports look empty.

Save behavior

Edits are local until you click Save changes. The amber "unsaved changes on N levels" indicator counts how many cards have pending edits. Hitting save loops through every dirty row and writes them in sequence — if one fails (e.g. you blanked out a singular label), the toast surfaces the error and the others remain dirty.

Singular labels are required

Blank singular labels are silently skipped during save. If you can't get a change to stick, check that you haven't accidentally cleared the singular field.

Sample translations

If your org is bilingual (set in Settings → Language) the labels are stored as plain strings. To translate them you'd add the localized strings to the t() lookup keys at org_structure.level_label.<id> in your locale JSON. For most churches the level labels are spoken the same way in English and Spanish — Cell and Célula are the only common pair.

Next steps

• Create units at each level now that the labels exist.
• Wire up parent-child relationships once you have units to nest.
• Assign leaders so shepherds get the right scope from day one.