00 · Foundation / Information Architecture
System map & role-gated navigation
Top-level IA for RCL Hub 2.0. Routes are gated by the RBAC matrix in §8.2. Learners see governance + communication; RCL Members add proposal management + tasks; Teachers add oversight + school analytics; DBE adds provincial/national rollups + user management.
01 · Authentication / Login & Registration
Get in fast, even on a borrowed phone
OAuth2 + JWT (§8.1). Login favours phone number — most learners share family devices. Registration is a 3-step wizard: school code → role → identity. The school code resolves school + province, eliminating two screens of pickers.
- 1Single primary action. Phone + password only. OAuth2 token exchange happens server-side; refresh stored in secure storage.
- 2School code resolves geography. One input replaces province → district → school cascading dropdowns. School + province auto-populated for analytics rollup.
- 3Role-gated registration. RCL Member & Teacher require verification (school admin or coordinator approval). DBE is invite-only — no public selector.
- 4Low-bandwidth banner. Surfaces when sync engine detects high latency; UI strips images and defers non-essential JS.
02 · Mobile · Learner / Home Dashboard
A landing pad for the active learner
First screen post-login. Surfaces what needs attention right now: open votes (with deadline urgency), assigned tasks, upcoming meetings, and a recent activity feed. The single-screen rule of §7.2 (<3 clicks) means voting is reachable from this screen in two taps.
- 1Personal greeting. First-name + role context. Sets the tone — this is your hub, not a generic dashboard.
- 2Open votes top of stack. Time-sensitive items first. Coloured urgency bar (red <24h, amber <7d, neutral) gives instant deadline read without numbers.
- 3Single next meeting. Calendar lives elsewhere; home shows only what's next. RSVP is a one-tap action — counts toward attendance event stream.
- 4Offline queue is visible. Per §11.2 delta sync. The user always knows what's saved, what's pending, what'll happen on reconnection. Trust over surprise.
03 · Mobile · Learner / Proposals List
Browse, filter, vote
Primary governance surface. Lists proposals from the learner's school + grade scope (filterable). Status pills indicate stage; the filter chip row is sticky so the user always knows what's filtered. The FAB is hidden for plain Learners — visible only for RCL Members who can submit on behalf of their committees.
- 1Inline vote action. Quick yes/no/abstain sheet opens from this button. Full proposal detail is a tap on the card body — two patterns coexist.
- 2Scope filter is governance-aware. Reflects committee membership from User Profile Service. "My committee" is hidden if the learner has no committee role.
- 3FAB is role-gated. Plain learners cannot submit proposals directly — they raise issues via Submit Issue (Communication Service), which routes to RCL members for proposal authoring.
04 · Mobile · Learner / Proposal Detail · Vote
The vote, recorded in <1 second
Acceptance criteria from §15: user can vote once, vote recorded within 1 second, results update in real-time. The vote panel is anchored bottom — always reachable on long proposals. Live results bar shows current standing without revealing identities. Discussion is post-vote only to reduce strategic voting.
- 1Live results visible pre-vote. Trade-off: privacy of trends vs. strategic voting risk. Mitigated by anonymized totals + post-vote-only commentary.
- 2Bottom-anchored vote panel. On long proposals the user never has to scroll back. Three options (Yes / No / Abstain) — abstain still counts toward quorum.
- 3Real-time updates. WebSocket subscription on PROPOSAL_VOTE_CAST event (§6.1). Falls back to polling on poor connections per §11.
- 4Quorum + threshold visible. Governance transparency. Both lifted from Governance Service config; school-level governance can override defaults.
05 · Mobile · RCL Member / Submit Proposal
Author a proposal in three steps
Available to RCL Members. Wizard structure guards against half-finished submissions while keeping each step short. Drafts are first-class citizens — saved offline, picked up on any device. The "supporting context" step accepts photo + voice note (low-bandwidth alternative to typing long descriptions).
- 1Closed category list. Avoids long-tail tags. Categories are configurable per province by DBE Admin to support analytics rollups.
- 2Voice note is a first-class input. Speech-to-text + audio playback. Reduces friction for typing-averse users; transcript indexed for search.
- 3Voting setup with school defaults. Default values come from the school's governance config — most authors won't change them. Power users can.
06 · Mobile · Shared / Meetings & Tasks
Workflow Service, made friendly
Two surfaces from one service (§3.1 Workflow Service). Meetings: schedule, RSVP, agenda, minutes. Tasks: assigned items with due dates and status. Both expose Kanban-style state transitions on the back end but are simplified to lists on mobile to keep the <3-clicks rule.
- 1Hybrid meetings, native. Virtual flag triggers a "Join" button at meeting time. Integration Service handles Teams/Zoom/Google Meet via meeting URLs in the agenda payload.
- 2Agenda is structured, not free text. Time-blocked items linked to proposals/decisions. Drives auto-generated minutes draft after the meeting.
- 3Tasks have provenance. "From: Mrs Khumalo" makes the source visible — system-assigned tasks (e.g., post-vote review) are labeled "From: System".
07 · Mobile · Shared / Messages
Channels for the governance, DMs for the rest
Communication Service (§3.1). Channels are auto-provisioned per committee + grade group; learners cannot create cross-school DMs (safeguarding). Teachers see all channels their committees own. All messages are scanned by content-moderation pipeline before delivery.
- 1Channels are work surfaces. Pinned proposals, files, and meeting links live alongside chat. The boundary between "messaging" and "doc collab" softens here.
- 2Safeguarding banner. DMs only allowed within same school + grade by default. Cross-grade requires teacher-approved buddy/mentor role. Visible reassurance to learners + parents.
- 3Moderation is event-driven. Each MESSAGE_SENT event runs through the moderation pipeline (§6.1) — flagged messages held + escalated to a teacher's review queue.
08 · Mobile · Shared / Notifications & Profile
Stay caught up, manage your account
Notification Service (§3.1) renders push, SMS, email and in-app surfaces. The in-app inbox is the source of truth — push is best-effort. Profile is the entry point for settings, school transfer requests, and offline storage management. The footer surface "More" tab houses both.
- 1Urgency-coloured icons. Red dot for closing votes, neutral for FYIs. Unread state shows a teal dot — read state collapses opacity.
- 2Storage management visible. Per §11.1 (SQLite cap on mobile). Users on low-end devices need to reclaim space — sync flag triggers force-clean of cached media.
- 3Channel × event-type matrix. Power-user pattern simplified to mobile. Defaults are conservative (push for time-sensitive only) to avoid notification fatigue.
09 · Web · RCL & Teacher / RCL Member Dashboard
The operating console for active members
Web-first surface — most RCL Member work happens at a laptop (drafting proposals, reviewing analytics, scheduling). Mobile parity exists but the desktop layout makes simultaneous workstreams legible: pending decisions on the left, activity on the right, calendar always reachable.
- 1"Needs attention" is a unified queue. Merges votes, tasks, and drafts in one priority-ordered list. The user shouldn't have to sweep three tabs to know what's outstanding.
- 2Activity feed = event stream. Reads directly from the Kafka event topic (§12.1) — every event type from §6.1 surfaces here, filtered to the user's committee scope.
- 3Sync indicator in topbar. Persistent across all web screens. Click to see queue depth, last sync timestamp, force resync.
10 · Web · Teacher / Committee Management
Committees, at a glance
Teacher oversight surface. Each committee is a Workflow Service container — members, recurring meetings, decisions, and a backlog. Cards show vital signs (activity, attendance, pending decisions). Drill-down opens a full committee workspace (out of scope for v0.1 wireframes).
- 1Open decisions surface accountability. A decision = a proposal or motion the committee owes a vote on. High counts trigger nudges in the activity feed.
- 2"At risk" is a derived health score. Computed from meeting cadence + attendance + activity. Teachers can drill in to investigate; learners don't see the label.
- 3Approval queue lives in the sidebar. Lerato proposed an ad-hoc committee — Mrs Khumalo approves, declines, or asks for revision. Audit-logged either way.
11 · Web · Analytics / School Analytics
Engagement, quantified
Analytics Service surface (§3.1, §12.2). School-tier dashboard for Teachers and senior RCL members. KPIs roll up grade-level participation; charts decompose by category, grade, and time. Data is read from the warehouse (§12.1: Kafka → Spark → DW), not the operational DB — sub-second response is non-goal here.
- 1Two metrics, one chart. Active learners (volume) and vote participation (engagement quality) tell different stories — overlaying them is the value.
- 2Weak grade is highlighted. G11 below threshold gets a soft tag. Single-glance signal — Mrs Khumalo knows where to focus this week.
- 3Decisions log = governance audit trail. Sortable, filterable, exportable for DBE compliance reports. Every row links to the proposal artefact + audit log entry.
12 · Web · Analytics / Provincial & National Dashboard
The view from Pretoria
DBE-tier dashboard. Aggregates 20,000+ schools and 6M+ learners (§1.2 scope). Geographic heatmap surfaces participation gaps; trend lines show national engagement; theme detection clusters proposal categories into emerging issues. All drill-downs respect data-locality and PII rules — no individual learners visible at this tier.
- 1Heatmap as pattern detector. KZN's drop is visible at a glance. Click-through to provincial dashboard zooms in to district + school grain (gated by data minimisation rules).
- 2NLP-clustered themes. Proposal titles + descriptions vectorised; topics clustered nightly via Spark job. Surfaces issues DBE policymakers wouldn't see in raw category counts.
- 3No PII at this tier. Per §8 + POPIA: officials see aggregates only. Drill-down to individual learners requires elevated audit-logged access (not in v0.1 wireframes).
13 · Web · DBE Admin / Users & Permissions
Identity Service, operationalised
Per §3.1 + §8.2 RBAC matrix. Search, filter, audit, and modify role assignments at any scale. Bulk actions for school/district onboarding. Side panel handles individual edits without leaving the list — a pattern that scales from 10 to 10,000 users.
- 1Bulk CSV import = onboarding lifeline. 22k schools cannot be invited one-by-one. CSV maps to User + School entities (§4.1). Failures show inline; partial imports allowed.
- 2Side panel keeps context. Edits don't take you off the list — adjust role on one user and the row updates in place. Faster than a modal-per-edit.
- 3Permissions are derived, not editable here. They follow from role per the RBAC matrix. Per-user overrides are intentionally absent — keeps the matrix the single source of truth.
15 · Extensions / Alerts
System-pushed alerts, not action notifications
Distinct from the notification inbox (08). Alerts are top-down: DBE announcements, school-wide emergencies, safeguarding follow-ups, platform incidents. Three severity tiers — Critical (red banner, blocking acknowledgement), Warning (amber, dismissible), Info (teal, ambient). Acknowledgement is audit-logged so DBE can prove a message reached learners during emergencies.
- 1Critical alerts are blocking. Modal-style overlay; the app pauses until acknowledged. Reserved for safety/emergency only — abuse erodes trust.
- 2Acknowledgement is auditable. Stored against user + timestamp + alert ID. DBE can prove an emergency message reached a known recipient — required for incident reporting.
- 3Info alerts ≠ marketing. Platform updates only (new features, planned downtime). Editorial content lives in Stories (19), not here.
- 4Source authority is visible. Every alert shows who issued it (Principal / DBE / Platform). Anti-spoofing — only verified senders can issue alerts to a given scope.
16 · Extensions / Quotes
A small dose of inspiration, daily
Lightweight content surface — a rotating "quote of the day" on home, a browsable gallery, and an RCL-member submission flow. Curated, not free-for-all. Categories aligned to school values: Leadership, Ubuntu, Service, Excellence, Perseverance. Shareable card design for WhatsApp/Instagram.
- 1Daily rotation, deterministic. Same quote shown to everyone in a school per day — creates conversation. Algorithm cycles through curated set; learner can tap "Save" to keep favourites.
- 2RCL-only FAB. Plain learners can suggest via Submit Issue (Communication Service); only RCL Members + Teachers see the direct submission FAB. Keeps curation quality high.
- 3Moderation queue. All submissions go through the RCL coordinator/teacher for approval. Copyright + appropriateness check. Approved quotes enter the rotation for that school only.
- 4Shareable card design. "Share" generates an Instagram-square image with school branding + handle attribution — small organic-marketing surface for the platform.
17 · Extensions / Global Search
One panel to find anything
Cross-entity search — proposals, people, channels, meetings, stories, quotes. Mobile = full-screen overlay (tap search icon). Web = ⌘K modal. Results grouped by type with entity-filter chips. Strictly role + school scoped: a learner can never search across schools or see non-public data they don't already have permission for.
- 1Quick-jump shortcuts. Empty-state isn't wasted — it surfaces probable next-actions. Reduces "search to navigate" friction for the first few weeks.
- 2Search dovetails with AI. If query is question-shaped ("what's the status of…"), suggest the AI handoff. Doesn't replace search results — augments them.
- 3Actions in results. Power-user pattern from Linear/Superhuman — search isn't just retrieval, it can spawn creation. Web only initially.
- 4Scope is non-negotiable. Backend search index partitioned by school_id. A learner querying "Lerato" can never match learners outside their school, even by exact name. Cross-school search is DBE-only.
18 · Extensions / Calendar
All the dates that matter, layered
A wider view than Meetings (06). Layers: RCL meetings, voting deadlines, school events, exam periods, SA public holidays, personal tasks. Mobile shows an agenda list anchored to today; web is a full month grid. Toggleable layers — a learner can hide what's irrelevant. ICS subscription for external calendars.
- 1Agenda over month-grid on mobile. Vertical lists scroll naturally; tiny calendar cells on a 360px screen are noise. Month grid is web-only.
- 2ICS subscribe, not export. Users connect their personal Google/Apple/Outlook calendar to the hub feed — automatic updates beat one-time .ics downloads.
- 3Exam-prep blocks meetings. School admin defines exam periods; the platform suppresses non-essential meeting invitations during those windows. Workflow Service rule.
- 4Public holidays via SA API. Auto-fetched annually from the SA government calendar feed — no manual maintenance.
19 · Extensions / Stories & blog
Good stories, profiled
Long-form editorial surface. RCL coordinators and teachers publish stories profiling learner achievements, RCL initiatives, and leadership lessons. Different from proposals (which are operational) and quotes (which are atomic). Reactions allowed; comments moderated. National DBE-curated stories cross-syndicate to all schools.
- 1National syndication. DBE-published stories appear on every school's feed (tagged "National"). School-published stories stay school-scoped unless explicitly nominated for national review.
- 2Reactions ≠ likes only. Multi-emoji reactions (♡ 👏 🤔) read better as engagement signal — useful for editorial decisions about what resonates.
- 3Comments moderated by default. Held in queue; teacher releases. Reduces moderation load via auto-allow for established commenters (5+ approved comments).
- 4Consent on profiles. Stories naming/featuring identifiable learners require parent consent — gated at the publish step. POPIA + safeguarding driven.
20 · Extensions / Resources & video
A library of how-to, training, and reference
YouTube-embedded video playlists + downloadable resources (PDFs, templates). Organised into playlists by purpose: Platform How-to, Leadership Training, RCL Highlights, Inspiring Stories. Videos play inline; no native upload — YouTube is the host of record. Resources are scoped: national content from DBE, plus school-specific content.
- 1Playlists, not flat library. Horizontal-scroll rails per playlist read better on mobile than long alphabetical lists. Each rail has a "see all" gate.
- 2YouTube embed visibility. Player branded as YouTube — sets correct expectations (ads will play, comments off-platform) and avoids implying RCL Hub is the host.
- 3oEmbed for metadata. YouTube oEmbed API auto-pulls title + thumbnail + duration on paste. Curator doesn't retype anything.
- 4No native uploads. Hosting video at school scale is a cost and moderation nightmare. YouTube does both for free. Trade-off: dependency on a 3rd party.
21 · Extensions / Theme & appearance
Personal and campaign theming
Two distinct features under one roof. Personal: light/dark/system + accent colour + font size for accessibility. Campaign: school or DBE-issued themes for awareness months (Mental Health, Heritage Month, 16 Days of Activism) — applies a colour overlay, optional banner, and a curated content rail.
- 1Brand-safe palette only. 5 accent options pre-validated against teal-on-white WCAG contrast. Free-pick colour wheels lead to inaccessible UI.
- 2Text size is per-device, not per-account. Lives in local storage. A user on a phone vs a school laptop may want different defaults.
- 3Campaign themes are DBE-issued. Schools don't create their own — keeps the surface coherent across the country. Pre-canned calendar: Mental Health (May), Youth Month (June), Heritage (Sept), 16 Days (Nov-Dec).
- 4Schools can opt out. Some topics (e.g., 16 Days of Activism) involve sensitive content — school principals can disable specific campaigns for their community.
22 · Extensions / AI assistant
RCL Buddy — grounded, role-scoped, escalates to humans
A focused AI helper, not a general chatbot. Knowledge base: platform FAQs, school's governance docs, RCL handbook, current open proposals, the user's own data. Three rules: (1) always cite sources, (2) role-scoped — only sees what the user can see, (3) escalates anything safeguarding-related to a human teacher.
- 1Brand the AI distinctly. "RCL Buddy" with a friendly mark — sets expectation it's a helper, not a generic ChatGPT clone. Beta badge sets expectations honestly.
- 2Citations are non-negotiable. Every factual answer links to its source — constitution clause, governance config, proposal record. Builds trust + enables verification. Refuses to answer when no source is available.
- 3Safeguarding triggers an explicit handoff. Classifier on inputs detects bullying, abuse, self-harm, mental health crises → AI stops trying to solve, switches to support-and-route mode with pre-vetted resources. Conversation is logged (with consent) for the safeguarding team.
- 4Role-scoped retrieval. RAG index partitioned by role + school. A learner querying "show me the budget" cannot retrieve documents they can't access through the normal UI. AI does not bypass RBAC.
14 · Reference / Legend & conventions
How to read these wireframes
Visual conventions used throughout the deck, plus what these wireframes deliberately leave out. Wireframe-fidelity = structure, hierarchy, and interaction pattern. Visual design (typography, brand, micro-copy, illustration) is the next milestone.
Wireframe primitives
Image / media placeholder
Dashed border + diagonal cross. Final visual unspecified.
Avatar / person
Circle outline. Initials/photo come later.
Icon
Square or circle outline. Shape ≠ semantic — final icons TBD.
Buttons
Status & signals
Tags & pills
Urgency colours
Annotation pins
Sync states
Device targets
Mobile phone (primary)
360 × 740 viewport · Android Chrome PWA · ≥80% of learner traffic. Designed for one-handed use, low bandwidth, and devices with 2GB RAM.
Web (admin / oversight)
1280 baseline · scales up to 1440. Used by RCL members for authoring, by Teachers + DBE for oversight + analytics. Same component library, denser layout.
Tablet
Out of scope for v0.1 — the mobile layout reflows to fill, but no tablet-optimised variant is specified.
What's not in here yet
Final visual design. Typography, brand expression, illustration system, dark mode.
Final copy. Microcopy and tone-of-voice will go through DBE review before lock.
Multilingual layouts. isiZulu, Sesotho, Afrikaans, etc. — string lengths can change layouts; needs a separate audit.
Accessibility specifics. Contrast, focus rings, screen-reader labels — applied during build phase against WCAG 2.2 AA.
Empty states & errors. Each screen has a happy path here; first-run, empty, and error variants are TBD.
Learning Service surfaces. Per §3.1 — content, progress, gamification — descoped from v0.1 wireframes; covered in next iteration.
Provincial dashboard. Variant of National (12) with one-province scope; same components, different filter defaults.