easySPEAK — Feature × Role Access Matrix

Executive summary

easySPEAK has three parallel legacy permission layers plus a fourth, newer one — the API permissions table — which is the only layer that is data-driven and centrally maintainable. The matrix below documents every feature against every role, and doubles as a migration tracker: each feature is either already covered by the central API model or still guarded by scattered legacy checks.

The practical consequence: "less is more" doesn't require new enforcement machinery. The API layer's 8 grant types are a good model. What's needed is (1) named role presets over the existing officer flags, (2) feature-by-feature API coverage of the legacy-only areas, each an independently testable step, and (3) this matrix maintained as the single registry of who-can-do-what.

Findings worth a decision at the meeting

How access control actually works today — four layers

The near-binary reality: counting actual checks across all web pages — binary is_officer 63×, district_officer 32×; the 17 granular flags appear 233× but mostly toggle in-page buttons (is_vpe 50×, edit_users 25×, edit_meeting 21×, schedule_speakers 20×), not page access. Different officer titles only differ through whatever flags a club happened to set.

The Feature × Role matrix (as-is)

Roles from District Director down to guest, as requested. The API column marks coverage by the central permission model — every — there is a future testable migration step.

1 · Meetings & agenda

2 · Roles & participation

3 · Education — Pathways, workbooks, evaluations

4 · Charts, reports & DCP

5 · Members & club directory

6 · Communication

7 · Club website, portal & media

8 · Events, payments & voting

9 · District / multi-club & 10 · System admin

Reading the API column as a migration tracker: meetings, roles, education, forums, messaging, notifications, portal, DCP and voting are already centralised. The big legacy-only blocks — each a candidate for the next testable steps — are member management, club data / Club Control Panel, email tooling, reports, district features, and the admin panel.

The API permission model — 68 actions, grouped

Grant key: SU same-user · CM club member · CO club officer (any ti_code 1–99) · VPE (ti_code=2) · MC meeting chair · BM buddy/mentor · AD admin. No action grants anyone.

Enforcement: every authorised stored procedure's first statement is sp_validate_api_permission(action, user, club, other_member, meeting) — short-circuit OR over the grant columns. OAuth scopes (meetings:read, profile:read, …) gate the app before the role matrix applies. Full row-by-row seed data: PATCH v2.23 → v2.34.

Proposed target model — "less is more"

Keep the enforcement mechanics (they work). Collapse the combinations in the wild with named role presets, and let each preset double as a view preset — the "different view and default features per role" ask falls out of the same model, because apps already pre-render UI from sp_get_user_permissions and switch_view.php already toggles officer/member views.

Presets are applied when an officer is appointed; per-club overrides remain possible but become flagged, auditable exceptions. Result: same 8 API grant types, ~7 presets covering ~95% of officer rows, one registry (this matrix). Fewer combinations — not fewer capabilities.

Design note — speech slots as "dibs" placeholders

Allocating speeches ahead of time needs its own careful flow, distinct from role assignment. Proposed lifecycle:

1. Claim ("dibs"): a member says they want to speak and gets a placeholder, not a confirmed speech. Fairness rules apply only under contention: 3 slots and 3 requesters — no rules needed, everyone speaks. 6 requesters for 3 slots — recency decides, surfaced as traffic lights next to each requester (e.g. red = spoke at the previous meeting, amber = spoke within the fairness window, green = due a slot). Small clubs will rarely see this; it matters as clubs grow, and seasonally. The data already exists (last_spoke, speech history) — the traffic light is a display over it, not new machinery. Competition-season wrinkle: contest preparation legitimately means giving the same speech more than once, and often visiting other clubs to hone it — so the rules need a contest-prep exception (or a club toggle to prioritise it), and repeat delivery of a marked contest speech shouldn't count against recency the same way as a new project. Cross-club recency: today each club only sees when someone last spoke there — a member of several clubs can show "never spoke here" while speaking weekly elsewhere. Fine when there's no contention; under contention the traffic light should optionally reflect overall recency. Speech history is stored per user (not per club), so a cross-club view is already queryable within an instance — and becomes universal after the planned 3-instance merge. Needs a visibility decision (does a club see activity at other clubs by default, or just an aggregate "spoke recently elsewhere" flag?).
2. Confirm: before a deadline, the member fills in the placeholder — picks their path/project and speech title. The agenda updates from "Speaker: (reserved — Paul)" to the real entry.
3. Release: if they don't confirm in time, or choose to step back, the slot is released — offered to the next requester or opened for general signup — rather than silently sitting as an empty placeholder on the agenda.

Most of the machinery exists (speech requests, agenda slots, notification preferences); what's missing is the explicit placeholder state, the fairness window, and the confirm/release transitions with reminders. This slots naturally into the API-first migration as its own testable work item.

Migration in testable steps

1. Adopt this matrix as the living registry (KB page). Every feature row carries a state: legacy-only → API-covered → legacy-check-retired.
2. Fix the cheap discrepancies now — F1 docs fix (1 line); F2 add buddy/mentor to sp_get_user_permissions; F3 document same_user bulk semantics. Three small, independent, testable MRs.
3. Seed the presets — one new table (phpbb_tm_officer_preset) + "apply preset" in officer admin. No enforcement change; pure data hygiene, verifiable by before/after flag comparison.
4. Per legacy-only feature: permission row → stored proc (validating first) → endpoint → point web/app at it. One feature per MR, each testable by direct CALL on the test DB + curl. Suggested order: member management → club data/Control Panel → email tooling → reports → district → admin panel.
5. Only then consider retiring legacy layers — by which point every access decision is named, central, and individually tested.