Known issues, deferred features and architectural TODOs

A live register: issue, context, priority, and the prompt it belongs in. Items are removed when resolved.

ARCHITECTURAL / DATA MODEL

A1 — School hierarchy is one level too flat

Issue: UK Schools currently acts as both a country grouping AND a specific institution. A school admin assigned to “UK Schools” sees all projects under it, which is wrong when multiple UK schools are in the system. Should be: LFTI root → Country grouping (UK Schools) → Specific school (Bristol Academy) → School admin scoped to their school only. Fix: Add one hierarchy level. System admin creates specific school nodes. Visibility scoping matches institution_id to specific school node, not country grouping. Priority: High — must fix before any real schools are onboarded. Context: Discovered during project setup testing with ukadmin.

A2 — parent_id is singular but relations[] expresses multi-parent

Issue: The node schema has a single parent_id for tree rendering, with multi-parent expressed via contains relations. This means a node that genuinely belongs to multiple projects only appears in one place in the tree. The other relationships are only visible in graph mode. Current behaviour: Correct and intentional for now. Tree view is one lens. Risk: Interchange nodes (sessions involving two institutions) will need careful handling — their parent_id should point to whichever institution initiated, with involves relations to the other. This discipline must be maintained. Fix when: Interchange nodes are built. Add a note in the interchange prompt to enforce this. Priority: Medium — document the convention clearly, enforce in interchange prompt.

A5 — Person nodes not attached to institution/project tree

Issue: All person nodes (dev seed users, wizard-created staff, class nodes) are currently root-level or loosely attached. They appear in the tree alongside LFTI and UK Schools which is wrong and will become confusing at scale. Should be: Person nodes sit under their most appropriate parent in the tree — institution node for staff/admins, class node for students, project node for facilitators. parent_id must be set correctly, not null. Fix: When creating person nodes via auth seed, project wizard, or manual capture — always set parent_id to the correct parent. Dev seed users should be reparented: system-level users to inst_lfti, institution-specific users to their institution node. Priority: Medium — fix in the same prompt as F21 (class roster) since that prompt creates person nodes properly anyway. Context: Identified during multi-user tree view testing. Issue: The filterNodesByVisibility() function uses a simplified institution_id match rather than full graph traversal (walking contains chains up to find which institution a node belongs to). Current behaviour: Works correctly for directly tagged nodes. May miss nodes that inherit visibility from a parent without an explicit institution_id in their own meta. Fix: Implement recursive parent traversal in filterNodesByVisibility(). Check meta.institution_id on the node first; if absent, walk parent_id chain until an institution node is found. Priority: Medium — needed before multiple real institutions are using the system simultaneously. Context: Noted in auth prompt as deferred.

A4 — Partners visibility rule not fully implemented

Issue: The _visibility: "partners" rule is defined (visible to institutions connected via involves or responds_to relations) but only a simplified version is implemented. Full graph traversal to determine partnership is deferred. Fix: When interchange nodes are built, implement the full partners check: a user can see a partners node if their institution_id has an involves or responds_to relation to any ancestor of that node. Priority: Medium — needed for interchange feature. Context: Noted in auth prompt as deferred.

FEATURES DEFERRED TO LATER PROMPTS

F1 — Tool selection UI

Issue: Phase nodes currently show a nudge toward the reference tool library but have no guided tool selection flow. Should be: Filter-based tool cards (individual/group, indoor/outdoor, sync/async etc), select 1–3 tools, progress to next phase. Three selected triggers a move-on prompt but fewer is allowed. Priority: High — next major feature after project setup. Prompt: tool-selection-prompt.md (to be written)

F2 — Session flow and artefact capture

Issue: No UI for students to actually run a tool session and upload/create artefacts within a phase. Should be: Group selects a tool, runs the session, uploads artefacts as block nodes (images, text, drawings). Soft limit of 5 contributions per group per phase as a nudge. Priority: High — core student-facing feature. Prompt: session-flow-prompt.md (to be written)

F3 — Approval flow (async and live session mode)

Issue: Approval mode is set during project setup but the actual approval UI is not built yet. Should be:

• Standard (async): teacher sees a list of pending contributions, approves or flags with a note
• Live session mode: real-time feed of contributions, large approve button, designed for whiteboard display
• Flagged content returns to group with a note Priority: High — needed before any content is shared externally. Prompt: approval-flow-prompt.md (to be written)

F4 — Project dashboard Phase 3

Issue: Project dashboard (overview tab with progress grid, needs-attention items, upcoming sessions) not yet built. Phase 1 and 2 of project setup complete but dashboard is Phase 3. Should be: Progress grid showing contribution counts per phase, needs-attention notifications, participant summary, upcoming workshop dates. Priority: High — next step after current phase. Prompt: project-setup-prompt.md Phase 3 (continuation)

F5 — Observer project overview page

Issue: Observer role currently sees the same tree view as other users. Should have a dedicated read-only view. Should be: A clean page showing past and live projects with status indicators and approved Present artefacts only. No access to working nodes. Natural home for light analytics. Priority: Medium — needed before funders/external observers are given accounts. Context: Identified during multi-user testing.

F6 — Collaborative prioritisation tools UI (Stones in Circles etc)

Issue: Collate phase tools like Stones in Circles, Matrix Ranking, Pairwise Ranking are defined in the reference instance but have no interactive UI. Should be: Facilitator-run single-screen tool for stones/voting, matrix, pairwise. Student-facing display. Output saved as a prioritisation artefact node. Priority: Medium — needed for Collate phase sessions. Prompt: collate-tools-prompt.md (to be written)

F7 — Synthesis canvas placeholder

Issue: The Synthesis node in the Collate phase is explicitly marked as a placeholder. No collaborative drawing/compositing surface exists. Should be: A shared canvas where groups can produce a collective representation from Gather artefacts. This is the most technically complex piece of Collate. Priority: Low — deferred intentionally. Placeholder node exists. Do not build until Gather and basic Collate are working well. Context: Noted in PLA_TOOLS_REFERENCE.md.

F8 — Body Map facilitation protocol

Issue: Body Map tool node is marked _status: protocol_pending. Full facilitation protocol needs to come from Mary Manzole (Kamoto Artistic Director). Action required: Conversation with Mary Manzole to document the protocol. Update the Body Map node body with the authoritative facilitation notes. Priority: High — do not run Body Map sessions without this protocol documented. Context: Noted in PLA_TOOLS_REFERENCE.md.

F9 — Transect walk spatial data (GPS variant)

Issue: Transect walk currently supports low-tech (hand-drawn path, image upload). GPS-tagged high-tech variant is defined but not built. Should be: Optional GPS track on a transect walk contribution node. Geotagged observation points. Display on a map view. Priority: Low — secondary option, hand-drawn is primary. Context: Identified in Gather/Collate design discussion.

F10 — Student voting on tools

Issue: Students can see the tool library but cannot signal which tools they want to use. Should be able to vote/react without unilaterally adding a tool to the project. Should be: A reacts relation type. Student node reacts to a tool node with meta.reaction: "want_to_use". Facilitator sees these as requests on the phase node. Extension: Class-level collation of votes — the votes themselves go through a mini Collate process before the facilitator makes the final selection. Self-referential — the methodology for choosing tools is itself participatory. Priority: Medium. Context: Identified during reference instance visibility discussion. Class collation layer added during Phase 3 review.

F18 — Group instance nodes

Issue: No group instance node type exists yet. Group instances should be children of a tool instance node, carrying: member names and roles, modality (digital/paper), status (not started / in progress / submitted / uploaded by proxy). Should be: The facilitator view of a tool instance shows all group instances and their current state at a glance — who has submitted, who is paper-only, who hasn’t started. Priority: High — needed before any real sessions run. Context: Identified during tool instance design discussion.

F19 — Coordinate clustering for digital transect walk collation

Issue: When multiple group instances have image map annotations near the same coordinates on a shared reference image, the Collate view should surface this as a cluster with a frequency count — nudging toward the deduplication conversation without forcing it. Important constraint: This ONLY applies to digital image maps with shared pixel coordinates. Hand-drawn transects and maps cannot be clustered algorithmically — the reconciliation is a human participatory activity (see F23). Priority: Medium — needed for digital Collate phase of transect walk tool. Context: Identified during tool instance design discussion.

F20 — Contribution body + location as relational finding

Issue: The image map pin captures the where; the contribution body captures the why-it-matters. The Collate view should display both together for each cluster — not just “12 groups marked this point” but “here is what they said about it.” Should be: In the Collate surface, each coordinate cluster shows: frequency count, all group names that marked it, and all contribution bodies attached to those annotations, readable side by side. Priority: Medium — the essence capture surface for transect walk collation. Context: Identified during tool instance design discussion.

F21 — Class roster management

Issue: No formal class roster exists. Students are either person nodes added manually or not in the system at all. Group management cannot work properly without a class list. Should be: Lightweight person nodes for students — first name + last initial minimum (Tom P), no login required. Teacher enters roster via class node (paste or type list). Roster entries matched to full user accounts if student later gets one. Absent students markable per session, reversible. Priority: High — needed before group management (F22) works. Context: Identified during group management design discussion.

F22 — Group management view

Issue: No UI exists for assigning students to groups within a tool instance. Should be: Pre-Start view within a tool instance showing class list on one side, groups on the other. Every student starts unassigned. Teacher (or students) assigns to groups. View shows: unassigned students highlighted, groups with missing roles flagged, absent markers. Must be completable in under 5 minutes for a class of 30. States: unassigned / in group no role / in group with role / absent / arrived late (addable mid-session). Priority: High — needed before real sessions run. Context: Identified during group management design discussion.

F23 — Map Reconciliation as a Collate tool

Issue: Hand-drawn maps from Gather cannot be algorithmically clustered. The reconciliation of multiple hand-drawn maps into one agreed reference map is itself a meaningful participatory activity. Should be: A specific Collate tool instance type — “Map Reconciliation” — where input is a collection of hand-drawn map/transect images from Gather and output is a collaboratively produced single reference image. Groups compare drawings, negotiate what counts as the same place, produce an agreed version. Priority: Medium — add to reference instance tool library when Collate tools are built. Context: Identified during transect walk collation discussion.

F24 — Student group assignment and contribution permissions

Current state: Students are read-only — no “+ Add contribution” buttons visible at any level. Facilitator/admin can add contributions at tool instance level (class example) and to any group instance. This is an acceptable interim state for facilitator-led sessions. Problem: Without knowing which group a student belongs to, the system cannot grant contribution rights to their group only. Granting rights to all groups is too permissive. Three options:

Option A — Proper student accounts linked to group membership (long term) Students have login credentials. User record links to person_node. Person_node is a member of a specific group_instance. System knows who they are and what group they belong to. Requires F21 (class roster), F22 (group allocation), and F12 (invite/account creation). Also requires a safeguarding/data protection framework for creating accounts for minors.

Option B — Adhoc group token login (recommended interim) No individual student accounts needed. Each group_instance gets a short token/PIN (e.g. “GROUP1-X7K2”) printed on the group’s worksheet (F15). Any device entering that token gets group-scoped permissions for this tool instance — can add contributions to that group only, see that group’s work, nothing else. Token expires when tool instance is completed or manually invalidated. No email, no password, no personal data stored. Maps naturally onto the printable worksheet.

Option C — Hybrid (long term) Students with accounts get full individual identity and proper group assignment. Students without accounts use a group token as lightweight fallback. Both work simultaneously.

Recommended path: Build Option B alongside F15 (printable sheet) — the group token prints on the worksheet naturally. Option A/C follows when a data protection framework for student accounts is in place. Priority: High — needed before real student-facing sessions run. Context: Identified during contribution permission review. Issue: Current implementation adds tool references to a phase node but does not create a tool instance node as a child. The instance is where the live facilitation plan, session steps, timing, materials, and contributions should live. The reference tool node is the canonical definition; the instance is the running version for a specific class on a specific day. Should be: Selecting a tool creates an instance node (type: tool_instance) as a child of the phase node, with a references relation to the source reference tool node. The instance node inherits the facilitation steps from the reference as a starting point, which the facilitator can edit. Contributions attach to the instance, not the phase node directly. Priority: High — needed before real sessions run. Current contribution attachment to phase node is a temporary structure. Context: Identified during Phase 3 tool browser review.

F14 — Tool flow suggestions (greying/highlighting based on prior selections)

Issue: No recommendation layer exists to guide facilitators toward tools that complement what has already been selected in earlier phases or movements. Should be: When browsing tools for a phase, tools that flow well from previously selected tools are subtly highlighted. Tools that would be redundant or clash are subtly greyed. Based on feeds and sequence relations between reference tool nodes — data already exists in the graph, just not surfaced. Example: Body Map selected in Past→Gather → Story Circle and River of Life gently highlighted for Situation→Gather. Venn Diagram actual/ideal highlighted for any →Collate phase following a narrative Gather tool. UI pattern: Subtle — a small compatibility indicator on each card, not a hard block. Facilitator’s judgment always overrides. Priority: Medium — valuable but not blocking. Build after tool instances (F13) are working. Context: Identified during Phase 3 tool browser review.

F11 — Academic calendar display

Issue: Session dates are stored as ISO UTC. Display should be localised to each institution’s academic calendar (UK terms, NZ terms, Zambian school year). Current behaviour: Dates display as ISO or generic format. Fix: Add calendar localisation layer. Institution node carries meta.academic_calendar. Display layer translates ISO dates into the right term/week framing for each user’s institution. Priority: Medium — needed when multiple countries are running simultaneously.

F12 — Invite system for staff and students

Issue: Staff and student emails are stored in person node meta during project setup but no actual invite is sent. Should be: Email invite with a link that creates their account and associates them with the correct institution and project automatically. Priority: Medium — currently requires manual account creation by system admin. Context: Noted in project setup prompt as placeholder.

UI / UX BUGS

U1 — Wizard tab state loss on step switch

Issue: If a user enters details on the Schedule step (e.g. specific dates) then switches to another step and back, their edits are lost. Fix: Store wizard form state in a persistent local object rather than reading directly from DOM inputs on step change. Read from the object, write to it on every input event. Priority: Low — minor UX issue, doesn’t affect functionality. Context: Identified during project setup testing.

U2 — Student delete permissions too broad

Issue: Delete button is hidden for student role globally, but students should be able to delete nodes they themselves created (e.g. their own contribution block nodes). Fix: Check both role AND whether node.meta.created_by === state.currentUser.id before showing/hiding delete. Students can delete their own; cannot delete others’. Priority: Medium — before student-facing sessions go live. Context: Identified during multi-user testing.

U4 — Reference tool filter editor missing existing value picker

Issue: The filter tag editor on reference tool nodes shows current values as removable pills and a free-text “add value” input, but there is no way to see and select from existing values already used by other tools for that filter type. A facilitator adding “playing fields” to location has no way to know if another tool already uses “playing_fields” (underscore) vs “playing fields” (space) — leading to inconsistent values and broken filtering. Should be: The “add value” input should show a dropdown of existing values for that filter type (derived from all tool nodes’ meta, as per the filter pill source-of-truth fix) as the user types — a typeahead/autocomplete. Selecting an existing value ensures consistency. Free text entry still allowed for genuinely new values. Priority: Medium — important for filter consistency before many tools are edited. Context: Identified during filter editor review after Piece 1.

U5 — Reference tool filter tags layout is purely vertical, too long

Issue: Filter tag groups (format, location, modality, duration, tech_level) stack vertically, causing the tool node content section to scroll excessively. Each filter type takes a full row even when its values would fit inline. Should be: Filter tags laid out horizontally — filter type label followed by its value pills on the same row, wrapping only when necessary. Multiple filter rows should fit in one or two visual rows total rather than five separate vertical blocks. Compact, scannable, not overwhelming. Priority: Low — cosmetic but affects usability of the tool editor for anyone editing multiple tools. Context: Identified during filter editor review after Piece 1. Issue: As the node tree grows with multiple projects and reference tools, the left panel tree may become unwieldy. No virtual scrolling or lazy loading implemented. Fix: Consider collapsing all but the active project by default. Lazy-load children on expand rather than rendering the full tree on load. Priority: Low — not a problem yet, will become one at scale.

SECURITY / ACCESS CONTROL

S1 — No enforcement of reference node read-only status

Issue: Reference nodes (_level: reference) are currently editable by all authenticated users. This is intentional during development but should be locked down before real schools are onboarded. Fix: In save/delete handlers, check meta._level === 'reference' and require superadmin role to edit. Show read-only styling for all other roles (already partially implemented visually). Priority: Medium — before onboarding real institutional users. Context: Intentionally left editable for development convenience.

S2 — No HTTPS

Issue: Running on HTTP locally. Cookies marked secure: false for development. Must enable HTTPS before any deployment beyond local dev. Fix: Add SSL certificate (Let’s Encrypt for self-hosted, automatic on most cloud platforms). Uncomment secure: true on cookie settings in api/auth.js. Priority: High — before any external deployment. Context: Noted in auth prompt with a comment in the code.

S3 — No rate limiting on auth endpoints

Issue: Login endpoint has no rate limiting. Vulnerable to brute force attacks. Fix: Add express-rate-limit to the login route. 10 attempts per 15 minutes per IP. Priority: Medium — before external deployment.

CONTENT / METHODOLOGY

C1 — Several PLA tool nodes have thin content

Issue: Some tool nodes in the reference instance have brief descriptions rather than full facilitation notes. River of Life, Timeline, Peer Interview, Hot Seating, and Story of Self in particular need richer body content. Fix: Expand body text for these nodes. Draw from the source documents in the project (EQUINET toolkit, AFCAP slides, Episcopal Relief transect walk guide). Priority: Medium — before facilitators are using the reference instance as a planning resource.

C2 — No facilitation notes for Present phase tools

Issue: Present phase tool nodes (Short Video, Podcast, Zine, Social Channel) have descriptions but no facilitation guidance. Fix: Add practical facilitation notes — equipment needed, how to brief students, common pitfalls, time estimates. Priority: Medium.

C3 — Cross-cohort tool variants not fully documented

Issue: Several tools have cross-cohort variants described in PLA_TOOLS_REFERENCE.md (transect walk as cross-cohort presentation, body map comparison, river of life side-by-side) but these variants are not yet represented as separate nodes or documented as facilitation options within the tool nodes. Fix: Add variant block nodes under relevant tools, or expand tool node bodies with cross-cohort variant sections. Priority: Low — needed when interchange feature is built.

← All notes · More from LFTI