/Recent content on Bits DocumentationHugoen-US/docs/phase2-architecture/Mon, 01 Jan 0001 00:00:00 +0000/docs/phase2-architecture/<h1 id="phase-2-platform-architecture">Phase 2 Platform Architecture<a class="anchor" href="#phase-2-platform-architecture">#</a></h1> <p>This page describes the three shared platform pieces that landed in Stage 15 of the Phase 2 plan and that every subsequent V2 stage (Groups, Mentorship, Chapter Events, Search/Recommendations, Marketplace) consumes. Source of truth for behaviour is <code>plans/BITSAPP-PHASE2-PLAN.md</code> §0; this page is the architectural overview that the plan&rsquo;s §0.3 DoD item calls for.</p> <p>As of the Phase 2 GA cut, all three components run unconditionally — the Stage 15-era <code>BITS_PHASE2_ENABLED</code> gate has been removed.</p>/docs/phase2-architecture-dependencies/Mon, 01 Jan 0001 00:00:00 +0000/docs/phase2-architecture-dependencies/<h1 id="phase-2-architecture--dependency-graph--citations">Phase 2 Architecture — Dependency Graph &amp; Citations<a class="anchor" href="#phase-2-architecture--dependency-graph--citations">#</a></h1> <p>This page is the companion to <code>phase2-architecture.md</code>. The other page describes <strong>what</strong> the Stage 15 platform pieces (membership facade, job runner, search infrastructure) are. This page describes <strong>how</strong> every Phase 2 surface depends on them, with file-path citations so a new contributor can find the source quickly.</p> <p>If you&rsquo;re reading this for the first time, start with <code>phase2-architecture.md</code>.</p> <hr> <h2 id="1-the-platform-pieces-recap">1. The platform pieces (recap)<a class="anchor" href="#1-the-platform-pieces-recap">#</a></h2> <table> <thead> <tr> <th>Component</th> <th>Package</th> <th>Schema</th> </tr> </thead> <tbody> <tr> <td>Membership facade</td> <td><code>backend/internal/membership/</code></td> <td><code>schema/memberships/</code> (<code>memberships_membership</code> table)</td> </tr> <tr> <td>Background job runner</td> <td><code>backend/internal/jobs/runner/</code></td> <td><code>schema/jobs_queue/</code> (<code>jobs_queue_job</code> table)</td> </tr> <tr> <td>Search infrastructure</td> <td><code>backend/internal/search/</code></td> <td><code>schema/search/</code> (<code>search_document</code>, <code>recommendation_signal</code>, <code>recommendation_candidate</code>)</td> </tr> </tbody> </table> <p>All three components run unconditionally as of the Phase 2 GA cut; the Stage 15-era <code>BITS_PHASE2_ENABLED</code> gate has been removed.</p>/docs/campus-tab-and-chapter-events/Mon, 01 Jan 0001 00:00:00 +0000/docs/campus-tab-and-chapter-events/<h1 id="campus-tab--chapter-events">Campus Tab &amp; Chapter Events<a class="anchor" href="#campus-tab--chapter-events">#</a></h1> <p>This page covers the user-facing surfaces introduced in Stage 18 of the Phase 2 plan: the <strong>Campus</strong> tab on <code>/app/feed</code>, chapter events surfaced from the existing calendar onto each chapter&rsquo;s group page, and the per-category announcement subscription model that lets you mute one announcement bucket without losing the rest.</p> <p>The Campus tab is one of the <strong>default landing surfaces</strong> for every authenticated stakeholder — students, alumni, faculty, parents, and staff. It&rsquo;s where time-sensitive announcements (recess windows, chapter meetups, placement results) and chapter activity surface for the people in scope.</p>/docs/qa-and-testing/Mon, 01 Jan 0001 00:00:00 +0000/docs/qa-and-testing/<h1 id="qa--testing--three-layer-strategy">QA &amp; Testing — Three-Layer Strategy<a class="anchor" href="#qa--testing--three-layer-strategy">#</a></h1> <p>This page documents how we systematically verify that every page of the Bits webapp renders, every button has a working handler, and no critical user flow is broken. The strategy is <strong>layered</strong> so each layer catches a different class of bug at a different cost-per-test.</p> <table> <thead> <tr> <th>Layer</th> <th>What it catches</th> <th>Effort</th> <th>Run time</th> <th>Source of truth</th> </tr> </thead> <tbody> <tr> <td><strong>A — Page-render smoke</strong></td> <td>Dead routes, missing imports, broken role guards, console errors on mount</td> <td>Auto-generated</td> <td>~20 s for ~70 pages</td> <td><code>webapp/e2e/smoke-pages.spec.ts</code></td> </tr> <tr> <td><strong>B — Click-sweep</strong></td> <td>Click handlers that throw, dialogs that render blank, broken event wiring, undefined-prop crashes</td> <td>Auto-generated</td> <td>~30 s for ~600 click attempts</td> <td><code>webapp/e2e/click-sweep.spec.ts</code></td> </tr> <tr> <td><strong>C — Critical-path scenarios</strong></td> <td>Multi-step business flows: onboarding, donations, ticket purchase, moderation decisions</td> <td>Hand-written</td> <td>varies</td> <td><code>webapp/e2e/&lt;feature&gt;.spec.ts</code> (one per feature)</td> </tr> </tbody> </table> <p>Layers A + B are <strong>safety nets</strong> — cheap to run on every PR, cover the entire surface area, fail fast when a page is broken or a button stops working. Layer C verifies that the business logic on top still does the right thing.</p>/docs/role-guides/admin/phase2-admin-overview/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/admin/phase2-admin-overview/<h1 id="admin--phase-2-admin-surfaces">Admin — Phase 2 Admin Surfaces<a class="anchor" href="#admin--phase-2-admin-surfaces">#</a></h1> <p>A pointer-page for platform admins to find every Phase 2 admin surface and the handbook that goes with it.</p> <p><strong>Who this is for</strong>: anyone with the platform <code>admin</code> role.</p> <h2 id="where-things-live">Where things live<a class="anchor" href="#where-things-live">#</a></h2> <table> <thead> <tr> <th>Surface</th> <th>Admin route</th> <th>Operational handbook</th> </tr> </thead> <tbody> <tr> <td>Groups + chapters</td> <td><code>/admin/groups</code></td> <td><a href="../../handbooks/group-admin-handbook.md">Group admin handbook</a></td> </tr> <tr> <td>Mentorship programmes</td> <td><code>/admin/mentorship</code>, <code>/admin/mentorship/programmes/new</code>, <code>/admin/mentorship/programmes/&lt;id&gt;</code></td> <td><a href="../../handbooks/mentorship-operations-guide.md">Mentorship operations guide</a></td> </tr> <tr> <td>Marketplace deals</td> <td><code>/admin/marketplace/deals</code></td> <td><a href="../../handbooks/marketplace-partner-onboarding.md">Marketplace partner-onboarding workflow</a></td> </tr> <tr> <td>Marketplace partners</td> <td><code>/admin/marketplace/partners</code></td> <td>(same)</td> </tr> <tr> <td>Staff leave queue</td> <td><code>/admin/staff/leave-requests</code></td> <td>This page (see below)</td> </tr> <tr> <td>CMS announcements</td> <td><code>/admin/cms/announcements</code></td> <td><code>documentation/campus-tab-and-chapter-events.md</code></td> </tr> <tr> <td>Audit logs</td> <td><code>/admin/audit-logs</code></td> <td>(Phase 1)</td> </tr> </tbody> </table> <h2 id="admin-capabilities-phase-2">Admin capabilities (Phase 2)<a class="anchor" href="#admin-capabilities-phase-2">#</a></h2> <p><code>backend/internal/auth/capabilities.go</code> defines four named capabilities used by Phase 2 services:</p>/docs/role-guides/alumni/chapters-and-groups/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/alumni/chapters-and-groups/<h1 id="alumni--chapters--interest-groups">Alumni — Chapters &amp; Interest Groups<a class="anchor" href="#alumni--chapters--interest-groups">#</a></h1> <p>The Phase 2 Groups surface is the place where alumni keep in touch with their cohort and with peers who share an interest. Two flavours live behind one feature: <strong>alumni chapters</strong> (one per batch year, plus one per major city — both seeded automatically) and <strong>interest groups</strong> (member-created, free-form). Both share a common posts/members/events shell.</p> <p><strong>Who this is for</strong>: anyone whose primary role is <code>alumni</code> (verified). Some flows below are also available to students and faculty when a group&rsquo;s visibility allows it; this page is written from the alumni point of view.</p>/docs/role-guides/faculty/groups-and-events/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/faculty/groups-and-events/<h1 id="faculty--groups-events--announcements">Faculty — Groups, Events &amp; Announcements<a class="anchor" href="#faculty--groups-events--announcements">#</a></h1> <p>Faculty use the Phase 2 surfaces mostly to read — chapter events for outreach, announcements to stay current, occasional posting in interest groups. This guide covers what you&rsquo;ll actually do.</p> <p><strong>Who this is for</strong>: anyone whose primary role is <code>faculty</code>.</p> <h2 id="reading-the-campus-tab">Reading the Campus tab<a class="anchor" href="#reading-the-campus-tab">#</a></h2> <p><code>/app/feed</code> → <strong>Campus</strong> tab is your default landing surface for institute-wide updates. It shows pinned announcements (sorted by <code>pin_until</code> so the soonest-to-expire is at the top) plus the recent published-announcement stream visible to you.</p>/docs/role-guides/parents/campus-and-announcements/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/parents/campus-and-announcements/<h1 id="parents--campus-announcements--marketplace">Parents — Campus, Announcements &amp; Marketplace<a class="anchor" href="#parents--campus-announcements--marketplace">#</a></h1> <p>The Phase 2 surfaces parents touch are read-only: announcements scoped to parents, the Campus tab digest, and any marketplace deal that explicitly carries a <code>public</code> audience scope.</p> <p><strong>Who this is for</strong>: anyone whose primary role is <code>parent</code>.</p> <h2 id="where-to-find-it">Where to find it<a class="anchor" href="#where-to-find-it">#</a></h2> <ul> <li>Campus feed: <code>/app/feed</code> → <strong>Campus</strong> tab.</li> <li>Notification preferences: <code>/app/profile/notifications</code> — <code>cms.announcement.&lt;category&gt;</code> toggles.</li> <li>Marketplace: <code>/app/marketplace</code> (filtered to <code>public</code> deals only — institute, alumni, and chapter scopes are not visible to parents).</li> </ul> <h2 id="what-you-can-read">What you can read<a class="anchor" href="#what-you-can-read">#</a></h2> <p>The Campus tab shows announcements that:</p>/docs/role-guides/staff/leave-and-payroll/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/staff/leave-and-payroll/<h1 id="staff--leave--payroll">Staff — Leave &amp; Payroll<a class="anchor" href="#staff--leave--payroll">#</a></h1> <p>The Stage 21 Staff HR surface gives staff a self-service flow for leave requests, payroll-view, and payslip download.</p> <p><strong>Who this is for</strong>: anyone whose primary role is <code>staff</code>. Managers approving leave on behalf of a team see the admin queue surface — that&rsquo;s covered separately.</p> <h2 id="where-to-find-it">Where to find it<a class="anchor" href="#where-to-find-it">#</a></h2> <ul> <li>Submit/track leave: <code>/app/staff/leave</code>.</li> <li>Payroll breakdown: <code>/app/staff/payroll</code>.</li> <li>Payslip list + download: <code>/app/staff/payslips</code>.</li> </ul> <p>Source: <code>backend/internal/hr/service.go</code>, <code>webapp/src/routes/app/staff/</code>.</p> <h2 id="leave-requests">Leave requests<a class="anchor" href="#leave-requests">#</a></h2> <h3 id="submitting">Submitting<a class="anchor" href="#submitting">#</a></h3> <p><code>/app/staff/leave</code> opens a form with:</p>/docs/role-guides/student/mentorship-as-mentee/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/student/mentorship-as-mentee/<h1 id="students--mentorship-as-mentee">Students — Mentorship (as Mentee)<a class="anchor" href="#students--mentorship-as-mentee">#</a></h1> <p>The Mentorship surface pairs you with an alumni mentor for a time-boxed cohort. Matching is driven by a transparent skills + audience-fit score, with both sides consenting before the relationship starts.</p> <p><strong>Who this is for</strong>: students and early-career alumni applying for a mentor through a Bits programme.</p> <h2 id="where-to-find-it">Where to find it<a class="anchor" href="#where-to-find-it">#</a></h2> <ul> <li>Browse open programmes: <code>/app/mentorship</code>.</li> <li>Apply as mentee: <code>/app/mentorship/programmes/&lt;id&gt;/apply-mentee</code>.</li> <li>Your matches: <code>/app/mentorship/matches</code>.</li> <li>A specific match: <code>/app/mentorship/matches/&lt;id&gt;</code>.</li> </ul> <h2 id="how-matching-works">How matching works<a class="anchor" href="#how-matching-works">#</a></h2> <p>A mentorship programme is a cohort. Admins open a programme; mentors and mentees apply during the <em>open</em> window. When the admin runs matching, an algorithm produces deterministic mentor↔mentee proposals scored by skill overlap, audience fit, and remaining mentor capacity. Mentors accept or decline first; only after a mentor accepts do you (the mentee) see the proposal. Both sides must accept to activate the match.</p>/docs/role-guides/alumni/mentorship-as-mentor/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/alumni/mentorship-as-mentor/<h1 id="alumni--mentoring-as-mentor">Alumni — Mentoring (as Mentor)<a class="anchor" href="#alumni--mentoring-as-mentor">#</a></h1> <p>The Mentorship surface lets alumni offer their time to current students and early-career alumni through programme-driven matching. This guide covers the mentor side of the lifecycle.</p> <p><strong>Who this is for</strong>: alumni who want to mentor through a Bits-run programme. If you are a student looking for a mentor, see <code>mentorship-as-mentee.md</code> under the student role guide.</p> <h2 id="where-to-find-it">Where to find it<a class="anchor" href="#where-to-find-it">#</a></h2> <ul> <li>Browse open programmes: <code>/app/mentorship</code>.</li> <li>Apply as mentor: <code>/app/mentorship/programmes/&lt;id&gt;/apply-mentor</code>.</li> <li>Your matches: <code>/app/mentorship/matches</code>.</li> <li>A specific match: <code>/app/mentorship/matches/&lt;id&gt;</code>.</li> </ul> <h2 id="how-matching-works-in-one-paragraph">How matching works (in one paragraph)<a class="anchor" href="#how-matching-works-in-one-paragraph">#</a></h2> <p>A mentorship programme is a time-boxed cohort. Admins open a programme; mentors and mentees apply during the <em>open</em> window. When the admin runs matching, the engine produces deterministic mentor↔mentee proposals scored by a transparent weighted formula: <code>2*skills_overlap + 1*audience_fit + 0.5*capacity_remaining</code>. You as the mentor accept or decline first; only after you accept does the mentee see the match. Once both sides accept, the match enters the <em>active</em> state and you can schedule sessions.</p>/docs/role-guides/student/groups-and-search/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/student/groups-and-search/<h1 id="students--groups--search">Students — Groups &amp; Search<a class="anchor" href="#students--groups--search">#</a></h1> <p>A short guide for students using the Phase 2 group surface and the new global search.</p> <p><strong>Who this is for</strong>: verified students. Most flows here also work for alumni, faculty, and staff; this page covers the bits that matter most to students.</p> <h2 id="joining-interest-groups">Joining interest groups<a class="anchor" href="#joining-interest-groups">#</a></h2> <p>Students can join <code>public</code> and <code>institute</code>-visibility groups. <code>alumni</code>-only groups are off-limits even if you can see them in search results. Open <code>/app/groups</code>, browse the <strong>All</strong> or <strong>Recommended</strong> tab, click into a group, and <strong>Join</strong>.</p>/docs/role-guides/alumni/marketplace/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/alumni/marketplace/<h1 id="alumni--marketplace">Alumni — Marketplace<a class="anchor" href="#alumni--marketplace">#</a></h1> <p>Curated deals (coupons + partner-site links) from vetted partners, scoped to the BITS community. Phase 2 launches with ~20 seeded deals across categories.</p> <p><strong>Who this is for</strong>: alumni (and verified students/faculty/staff for deals scoped to the wider institute). Deal visibility honours each deal&rsquo;s <code>audience_scope</code>, so you only see deals targeted at audiences you belong to.</p> <h2 id="where-to-find-it">Where to find it<a class="anchor" href="#where-to-find-it">#</a></h2> <ul> <li>Deal grid: <code>/app/marketplace</code>.</li> <li>A deal card opens a modal in-place; deals are not on their own URL today.</li> </ul> <h2 id="browsing">Browsing<a class="anchor" href="#browsing">#</a></h2> <p>The grid surfaces:</p>/docs/role-guides/alumni/search-and-recommendations/Mon, 01 Jan 0001 00:00:00 +0000/docs/role-guides/alumni/search-and-recommendations/<h1 id="alumni--search--recommendations">Alumni — Search &amp; Recommendations<a class="anchor" href="#alumni--search--recommendations">#</a></h1> <p>Phase 2 ships a single global search box and per-user recommendation rails on the home page. Both are built on the same <code>search_document</code> index and the same audience-tag filter so what you see in search and what you see in recommendations honour the same scoping rules.</p> <p><strong>Who this is for</strong>: every authenticated user. This guide is filed under alumni because chapter/batch affinity makes the recommendations more useful for alumni out of the box; the surface itself is universal.</p>/docs/handbooks/group-admin-handbook/Mon, 01 Jan 0001 00:00:00 +0000/docs/handbooks/group-admin-handbook/<h1 id="group--chapter-admin-handbook">Group &amp; Chapter Admin Handbook<a class="anchor" href="#group--chapter-admin-handbook">#</a></h1> <p>This handbook is the operational reference for the people who run a group day-to-day: the group&rsquo;s admin and moderators. It covers the create flow, membership management, post moderation, chapter event creation, and broadcast announcements.</p> <p><strong>Who this is for</strong>: anyone with <code>MembershipRole = admin</code> or <code>moderator</code> on a group (interest or chapter). The platform-admin lens is in <code>documentation/role-guides/admin/phase2-admin-overview.md</code>.</p> <p><strong>Source of truth</strong>: <code>backend/internal/groups/service.go</code>, <code>backend/internal/groups/store.go</code>, <code>backend/internal/groups/types.go</code>. RPC contract: <code>protos/bits/groups/v1/groups.proto</code>.</p>/docs/handbooks/mentorship-operations-guide/Mon, 01 Jan 0001 00:00:00 +0000/docs/handbooks/mentorship-operations-guide/<h1 id="mentorship-programme-operations-guide">Mentorship Programme Operations Guide<a class="anchor" href="#mentorship-programme-operations-guide">#</a></h1> <p>This handbook is the operational reference for the people who run a mentorship programme: typically platform admins or staff with the <code>mentorship.match</code> capability. It covers programme setup, mentor onboarding, the match lifecycle, quality signals from the dashboard, and escalation paths when things go wrong.</p> <p><strong>Who this is for</strong>: anyone with the platform admin role (and by extension <code>mentorship.match</code>). The mentor and mentee guides are at <code>documentation/role-guides/alumni/mentorship-as-mentor.md</code> and <code>documentation/role-guides/student/mentorship-as-mentee.md</code>.</p>/docs/handbooks/marketplace-partner-onboarding/Mon, 01 Jan 0001 00:00:00 +0000/docs/handbooks/marketplace-partner-onboarding/<h1 id="marketplace-partner-onboarding-workflow">Marketplace Partner-Onboarding Workflow<a class="anchor" href="#marketplace-partner-onboarding-workflow">#</a></h1> <p>This handbook covers the end-to-end workflow for bringing a partner onto the Bits marketplace: from initial application through deal authoring, audience scoping, redemption monitoring, and payout settlement.</p> <p><strong>Who this is for</strong>: anyone with the platform admin role and the <code>marketplace.curate</code> capability. The user-facing marketplace guide is at <code>documentation/role-guides/alumni/marketplace.md</code>.</p> <p><strong>Source of truth</strong>: <code>backend/internal/marketplace/</code>. RPC contract: <code>protos/bits/marketplace/v1/marketplace.proto</code>. Admin webapp: <code>webapp/src/routes/admin/AdminMarketplace*.tsx</code>.</p> <hr> <h2 id="1-partner-application-out-of-platform">1. Partner application (out-of-platform)<a class="anchor" href="#1-partner-application-out-of-platform">#</a></h2> <p>V2 does not provide a self-service partner-application form. The application is handled out-of-platform — typically email, contract, then a Bits admin manually mints the partner record. This is intentional: marketplace is a curated surface and uncurated partner sign-ups would dilute trust.</p>