2Ix Volunteer Matching And Project Memory System Design - Source Excerpt 04 - UI and UX flows
Back to 2Ix Volunteer Matching And Project Memory System Design
Summary
This source excerpt begins near UI and UX flows and preserves the surrounding evidence from 2IA.org/agent-file-handoff/Archive/2026-05-19-2ix-volunteer-platform-research/2ix Volunteer Matching and Project Memory System Design.md.
**Source path:** 2IA.org/agent-file-handoff/Archive/2026-05-19-2ix-volunteer-platform-research/2ix Volunteer Matching and Project Memory System Design.md
The relationship between versions and events matters. **Events** answer “what changed and when”; **versions** answer “what was the canonical state at a specific point”; and **handoff packets** answer “what does the next person need to know right now.” This is the minimum memory model that can survive volunteer turnover.
A handoff packet should be mandatory for any assignment that is completed, paused, abandoned, or reassigned. The structured handoff flow should be this:
' ' ' mermaid
sequenceDiagram
participant V as Outgoing Volunteer
participant T as 2ix
participant M as Maintainer
participant N as Incoming Volunteer
participant R as Reviewer
V->>T: Start handoff / completion
T->>V: Require structured handoff template
V->>T: Submit blockers, state, links, artifacts, next steps
T->>M: Review handoff completeness
M->>T: Accept or request clarification
alt Successor assigned
T->>N: Notify incoming volunteer
N->>T: Acknowledge handoff
T->>R: Optional reviewer confirmation for sensitive work
T->>M: Mark work_item reassigned / resumed
else No successor yet
T->>M: Mark work_item paused with searchable handoff packet
end
' ' '
Every handoff packet should require these exact fields: **state summary, completed work, unfinished work, blockers, risks, next three actions, linked artifacts, linked code/issues/docs, people to ask, confidence level, and last verified date**. Catchafire’s emphasis on regular check-ins, shared folders, and actionable feedback provides the practical collaboration precedent here, while GitHub’s issue/PR linking and Projects custom fields provide the external-system linkage pattern. citeturn20view2turn17view2turn16view5turn23view0
The API should be **REST-first**, because the write patterns are transactional and role-sensitive. A read-optimized GraphQL layer can come later, but the operational core should be explicit and boring.
| Endpoint | Method | Purpose |
|---|---|---|
| `/v1/auth/oauth/{provider}/start` | POST | Start GitHub/GitLab/Google auth |
| `/v1/auth/oauth/{provider}/callback` | POST | Complete OAuth |
| `/v1/me` | GET/PATCH | Read or update own profile |
| `/v1/me/skills` | PUT | Replace normalized skill profile |
| `/v1/me/availability` | PUT | Replace availability model |
| `/v1/organizations` | POST | Create organization |
| `/v1/organizations/{id}` | GET/PATCH | Read or update organization |
| `/v1/organizations/{id}/verify-domain` | POST | Begin org verification |
| `/v1/projects` | POST | Create project |
| `/v1/projects/{id}` | GET/PATCH | Read or update project |
| `/v1/projects/{id}/readiness` | GET | Compute readiness score from docs/labels/activity |
| `/v1/projects/{id}/sync` | POST | Pull latest external state |
| `/v1/opportunities` | POST | Create opportunity |
| `/v1/opportunities` | GET | Search opportunities with filters |
| `/v1/opportunities/{id}` | GET/PATCH | Read or edit opportunity |
| `/v1/opportunities/{id}/publish` | POST | Move from draft to published |
| `/v1/opportunities/{id}/apply` | POST | Volunteer application |
| `/v1/opportunities/{id}/invite` | POST | Maintainer invite |
| `/v1/opportunities/{id}/candidates` | GET | Ranked candidate list with explainability |
| `/v1/applications/{id}/decision` | POST | Accept, pass, waitlist, interview |
| `/v1/assignments` | POST | Create assignment after match |
| `/v1/assignments/{id}` | GET | Get assignment |
| `/v1/assignments/{id}/updates` | POST | Add progress update |
| `/v1/assignments/{id}/complete` | POST | Mark ready for review |
| `/v1/work-items/{id}` | GET | Current canonical work-item state |
| `/v1/work-items/{id}/versions` | GET | Version history |
| `/v1/work-items/{id}/events` | POST | Append event |
| `/v1/work-items/{id}/state` | PUT | Update canonical version with optimistic locking |
| `/v1/work-items/{id}/links` | POST | Attach repo/issue/doc/discussion link |
| `/v1/work-items/{id}/timeline` | GET | Unified activity feed |
| `/v1/handoffs` | POST | Create handoff packet |
| `/v1/handoffs/{id}` | GET/PATCH | Read or edit handoff |
| `/v1/handoffs/{id}/accept` | POST | Accept handoff |
| `/v1/reviews` | POST | Create structured review |
| `/v1/search` | GET | Cross-entity search over opportunities, projects, handoffs, artifacts |
| `/v1/recommendations/me` | GET | Personalized recommendations |
| `/v1/reports` | POST | Report abuse or misrepresentation |
| `/v1/moderation/cases` | GET | Moderator queue |
| `/v1/webhooks/github` | POST | GitHub connector inbound |
| `/v1/webhooks/gitlab` | POST | GitLab connector inbound |
| `/v1/webhooks/jira` | POST | Jira connector inbound |
Two implementation rules are non-negotiable. **Every state-changing write should require optimistic version checks** so one maintainer cannot silently overwrite another’s update, and **every external link should store a small snapshot** such as title, status, assignee, and last synchronized timestamp so search still works even if the external service is temporarily unavailable. GitHub’s linked-issue model and Project synchronization make this hybrid snapshot pattern especially compelling. citeturn17view2turn16view5turn23view0
## UI and UX flows
The product experience should feel closer to **GitHub Issues + Projects + a skills marketplace** than to a generic volunteer signup form. The interface should make three things obvious at all times: **what the work is, why this match exists, and what happens next**. That is important because successful open-source and volunteer systems do not merely surface opportunities; they reduce uncertainty around norms, scope, and follow-through. GitHub’s contribution guidance, issue labels, community health files, and Discussions model all point in this direction. citeturn18view2turn17view0turn17view6turn22view0
The following screens are the key UX surfaces.
**Volunteer home and match inbox**
' ' ' text
+--------------------------------------------------------------------------------+
| 2ix | Search | My Matches | Active Work | Messages | Profile | Help |
+--------------------------------------------------------------------------------+
| Filters | Recommended for you |
| - Cause areas | ---------------------------------------------- |
| - Work type | [84%] Improve onboarding docs |
| - Skill level | civic-tech • docs • remote • 4h/week |
| - Availability | Why matched: doc-writing, async, beginner-fit |
| - Remote / onsite | Deliverables: setup guide + issue cleanup |
| - Duration | Actions: View | Save | Ask question | Apply |
| - Beginner-friendly | ---------------------------------------------- |
| - Verified org only | [79%] Triage accessibility issues |
| | ... |
|--------------------------------+-----------------------------------------------|
| Onboarding checklist | Active assignments |
| - Complete profile | - Docs guide revamp |
| - Add portfolio links | - Volunteer FAQ cleanup |
| - Set weekly availability | |
+--------------------------------------------------------------------------------+
' ' '
This screen should expose **why matched** on every recommendation card. That explainability is not cosmetic; it gives volunteers confidence and tells them how to improve their profile. Idealist’s search-by-skill/cause/location pattern supports the filter model, and Catchafire’s qualifications/work-sample flow supports the visible readiness checklist. citeturn16view3turn20view3
**Opportunity detail page**