Running the Cadet Corps, one chain of command A plain-language walkthrough of the new headquarters system — for review before we build it Design specification — one reporting tree, everything derives from it

One chain of command. Everything else follows from it.

A single reporting tree. Everything else is computed from it.

Every unit — from a school Battalion up to State — reports to exactly one headquarters above it. You tell the system who reports to whom once, and it works out the whole chain for you. From that single fact, everything else follows: who can see what, whose numbers add into yours, and which events a cadet can sign up for.

Every unit has exactly one parent HQ. Who you can see, whose numbers roll up to you, which events a cadet may register for, whose property aggregates into your book — all of it is derived from that one tree. Nothing about “who rolls up to whom” is stored twice.

The chain is flexible, not fixed. Usually a Battalion sits under a Regiment, but a Battalion can report straight to a Brigade if that's how it's organized. Set a Battalion's parent and the system already knows its Regiment, Brigade, Division, and State — you never re-enter them.

The tree is configured, not hardcoded. A parent may be any higher echelon, so a Battalion under a Brigade is legal. Setting a BN’s parent implies its whole ancestor chain automatically — the REG/BDE/DIV/State are never re-entered.

Four promises the system keeps

The four hard invariants

What this improves over today

What this supersedes in the live schema

Two things change from how the current tool works. Nothing already working is thrown away.

Everything else already close to right — cadets, cadet_record_entries, events / attendance, user_profiles — is kept and extended.

The things the system remembers

The newtools data model

Everything the system needs falls into a few plain buckets. Here's each one in everyday terms.

Additive-first: new tables and columns, legacy columns retained read-only through migration. All tables follow the repo’s data contracts — uuid keys, tracking columns, RLS shipped with the table.

You see your unit and everyone below you — nothing else

One predicate: see your unit and everything below it

Access follows the chain of command automatically. A leader sees their own unit and every unit beneath them — never a unit beside them, never above them.

A user assigned at echelon X sees exactly their subtree — nothing sideways, nothing above. The whole visibility model is one closure lookup, so there is no per-table ACL to keep in sync.

-- can the current user act on rows scoped to this unit?
cacc_can_see_unit(target_unit) :=
  EXISTS( super_admin )                       -- state/super: always
  OR EXISTS(
    SELECT 1 FROM user_unit_links l
    JOIN unit_closure c ON c.ancestor_id = l.unit_id
    WHERE l.user_id = auth.uid()
      AND c.descendant_id = target_unit )   -- target is in my subtree

Seeing vs. changing

Read is subtree-wide; write encodes the invariants

• Higher headquarters can read a Battalion's roster, but only the Battalion can change it.
• Equipment logbook entries can never be edited or deleted by anyone — a correction is a new entry, so the history is always intact.
• Report numbers can't be hand-edited. Higher HQ can add a note to a reporting period, but never change the figures underneath.

• Roster writes only by a user linked to that BN. Ancestors read rosters, never edit them.
• Property postings have no UPDATE/DELETE policy — append-only for everyone, incl. super admin. Corrections are compensating postings.
• SAR figures have no client write path — written only by the period-close routine. Ancestors write sar_annotations, never the numbers.

Signing in uses your Microsoft / CACC account. What you're allowed to do is set by which unit you're assigned to and your role.

Identity is Entra (authentication); authorization lives in user_unit_links.unit_id + primary_role + shop_admin_sections — the tree changes more often than tenant group membership and RLS must read it transactionally.

Real numbers live at the Battalion; everything above is addition

BN facts are atomic; ancestors only sum

All the real facts — who's on the roster, who showed up, what equipment is held — live at the Battalion. Every number a Brigade, Division, or State sees is simply those Battalion facts added up along the chain of command.

Every atomic fact has exactly one home BN — cadets.current_unit_id, event_attendance.home_unit_id, property_postings.unit_id. Summing disjoint BN partitions up the tree needs no dedup, and any parent number drills back to the BN rows.

Because each cadet, each attendance, and each piece of equipment belongs to exactly one Battalion, adding them up never double-counts — and any total can be traced straight back to the Battalions it came from.

How fresh are the numbers?

Consistency model — three tiers

Your own Battalion numbers are always live and exact. The big combined dashboards at Division and State refresh regularly through the day, and are made exact the moment a month is closed out.

The contract: BN-level numbers are always live; ancestor rollups are at-most-N-hours stale between refreshes and exact right after a period close or manual recompute.

Every level runs the same tools — with two key differences

Parallel modules at every echelon — two structural rules

How the tools connect

How the modules interlink

Setup builds the chain ──▸ decides what everyone can see
Roster ──feeds──▸ strength            Roster entry ──▸ the cadet's file
Attendance ──feeds──▸ activity
Property forms ──update──▸ the book    Issued gear ──▸ tied to a cadet

Super Admin tree ──defines──▸ scope of every module below
Roster ──is the source of──▸ SAR strength      Roster row ──▸ Cadet profile
Calendar attendance ──is the source of──▸ SAR activities
Property forms ──post──▸ ledger ──project──▸ book      Issue ──links──▸ Cadet

One action ripples through everything

Battalion module data-flow — one write, many reads

This is the heart of the design: the Battalion modules aren't separate tools — they feed each other. A cadet has to be on the roster before anything else can happen; from there, attending events, earning promotions and duty positions, passing certifications, and receiving equipment each land on that cadet's profile — on Form 13 (their career file) or Form 100 (their property). Follow the arrows.

The Battalion modules are a single connected graph, not independent CRUD screens. Each arrow is a real write path: a source module produces a fact that one or more downstream records read. Colors mark the kind of link.

Reading the map in one breath

The chain in words

• Roster & Records creates the cadet — identity, account, and profile. A cadet must be on the roster before any other module can touch them.
• The profile carries two forms: Form 13 is the cadet's career file (promotions, awards, and all admin/career data); Form 100 is their property record (everything issued to or held by them).
• Attending an event awards a ribbon onto Form 13 and posts an activity to the SAR.
• A duty assignment (S1) adds a leadership position to the cadet's duty history on Form 13 — and works the same way at every echelon.
• A PTA certification or a passed promotion test (S3) records onto Form 13.
• The property book changes only through four S4 forms — Requisition (ship items in), Report of Survey (remove unserviceable), Inventory (reconcile — and it flags when an inventory is due), and Issue Items (assign an item straight to a cadet). Issuing also drops the item onto that cadet's Form 100.
• Strength on the SAR is simply the roster count — nothing is entered twice.
• Delegate Access (S6) decides who on the roster can use which modules — at every echelon. Newsletter and Media Gallery (S5) publish unit news and photos, also at every echelon.

• Roster insert → cadets + membership + account; membership gates eligibility for every downstream module.
• Form 13 = projection of cadet_record_entries (appointment / award / badge / duty / order / promotion); Form 100 = projection of property_postings where issued_to_cadet_id is set.
• event_attendance.present → award entry (Form 13) + SAR activity for the home BN.
• cadet_duty_assignments (S1, per echelon) → duty entries (Form 13).
• pta_certifications + promotion_testing (S3) → certification / promotion entries (Form 13).
• property_postings are written only by the four S4 forms — requisitions (+), reports_of_survey (−), inventories (variance; surfaces an "inventory due" flag), issues (−, linked to cadet_id → Form 100). The book is their projection.
• delegate_access (S6) grants module_access to roster members; newsletters / media_gallery (S5) are unit-scoped, per echelon — no cadet-record writes.
• A module's owning shop resolves from module_shop_assignments (overrides the hardcoded staffSection default).

Every module, by shop

Module catalog by staff section

The full planned set, grouped by the shop that owns each (owners are re-mappable). “Every echelon” means the module also exists at Regiment, Brigade, Division, and State — scoped by the chain of command.

Default shop shown; resolved via module_shop_assignments. “Every echelon” = native per-unit at all echelons (scoped by unit_closure); above BN, Property/SAR are read-only rollups.

Get one Battalion fully working, then add the higher-level views

One battalion end-to-end, then the rollup layer

We build the Battalion experience end to end first, prove it works, then add the combined views for Regiment, Brigade, Division, and State on top. Each step ships on its own.

Rollups are pure functions of BN facts, so they’re added last without reworking BN modules. Each phase ships behind the existing module-flag system.

A few decisions we need from you before building

Decisions to confirm before build

These are policy calls, not technical ones — they shape how the system behaves. Here's what we'd suggest as the starting answer for each.

Full register in docs/DECISIONS.md. The load-bearing ones: