Project setup flow

This prompt builds the guided project setup experience for new institutional users. Read the full codebase before starting — particularly the existing node structure, the auth system, and how institution/project/cycle nodes are currently seeded in seedLFTI().

The goal: a teacher or facilitator at a new school can go from first login to a working project skeleton in under 2 minutes. Everything inferrable is pre-populated. Everything non-essential has a sensible default. Details can be added later.

Design principles for this feature

Speed over completeness. The setup flow must be fast. A teacher has 5 minutes before a class. Pre-populate aggressively. Make every field optional except the bare minimum to create the structure.

The right thing should be the obvious thing. In Zambia and elsewhere, excellent facilitators may find the tech challenging. The UI must make correct process hard to avoid and the next step always clear.

Group contributions as the default. The system nudges toward group work (4–6 students per group) rather than individual contributions. This reduces the approval bottleneck and matches the participatory methodology.

Approval protects without blocking. Student content is visible within the project immediately but requires teacher/facilitator approval before publishing externally. This is the default (async). A live session mode (sync) is available as a toggle.

Nodes are still the underlying structure. The setup wizard creates real nodes — institution, project, staff, class, cycle, phase nodes — using the existing API. The wizard is a friendly skin over node creation, not a separate system.

Institution landing page

When an institution_admin or facilitator logs in and their institution node exists but has no project nodes under it, the landing page (content area when the institution node is selected) shows:

┌─────────────────────────────────────────────────────┐
│                                                     │
│   Welcome to LFTI                                   │
│   [institution name]                                │
│                                                     │
│   ┌─────────────────────────────────────────────┐   │
│   │         + Start Your First Project          │   │
│   │         (large, accent colour, dominant)    │   │
│   └─────────────────────────────────────────────┘   │
│                                                     │
│   Complete your institution profile  →              │
│   (smaller, secondary, below the main button)       │
│                                                     │
└─────────────────────────────────────────────────────┘

Once at least one project exists, the institution landing page shows:

• Active projects as cards (title, status, date range, participant count)
• A smaller + New Project button in the top right of the projects section
• Creating a node of type project under the institution node also triggers the setup wizard

Project setup wizard

A full-screen overlay (same pattern as quick-capture but larger). Five steps, shown as a progress indicator at the top. Each step has a Back and Next button. Final step has a Launch Project button.

Progress indicator:

① Project basics  ② Schedule  ③ Participants  ④ Format  ⑤ Review

Clicking a completed step navigates back to it. Incomplete future steps are greyed out.

Step 1 — Project basics

Fields:

• Project name (text, required) — pre-populated with “[Institution name] — LFTI [current year]”
• Description (textarea, optional) — placeholder: “What is this project about? Who is involved? You can add this later.”
• Country context (auto-detected from institution node’s context tag — uk / nz / zambia / other) — shown as a read-only badge, editable if wrong
• Partner institution (optional) — search existing institutions by name. If selected, marks this as a paired project. Can be added later.

Pre-population logic:

• Institution name comes from the logged-in user’s institution_id → institution node title
• Year comes from current date
• Country context comes from institution node meta.context

Step 2 — Schedule

Fields:

• Project format (segmented control, required):

  • Intensive week — one continuous week
  • Weekly sessions — one session per week over a half-term or term
  • Custom — define your own structure

• Start date (date picker, required) — defaults to next Monday

• End date (date picker, required) — auto-calculated based on format:

  • Intensive week: start + 5 days
  • Weekly sessions: start + 6 weeks
  • Custom: user sets manually

• Workshop dates (appears after start/end are set) — a simple list of specific dates within the range. Pre-populated based on format:

  • Intensive week: Mon–Fri of the start week
  • Weekly sessions: same day each week for 6 weeks
  • Custom: empty, user adds dates manually

  Each date can have a label (e.g. “Day 1 — Past Gather”) — pre-populated with sensible defaults, editable.

• Academic calendar (select, optional) — UK / NZ / Zambia / Custom. Auto-detected from country context. Used for display formatting of dates.

Step 3 — Participants

Three sections, each collapsible:

Staff & facilitators:

• Add by name + email (they’ll get an invite — invite system is a placeholder for now, just store the email in the person node’s meta)
• Role: institution_admin / facilitator (select)
• Pre-populated with the logged-in user

Classes:

• Add class name (e.g. “Year 9 — 9A”, “Form 3 North”)
• Class teacher name + email (optional — can add later)
• Approximate student count (number input, optional) — used to suggest group sizes
• Multiple classes can be added with + Add another class

Groups (within classes):

• Auto-suggested based on student count: “Based on [n] students, we suggest [n/5 rounded up] groups of 4–5”
• Groups can be named or left as Group 1, Group 2 etc
• Students self-assign to groups within the app (organic — not set up by admin)
• Soft content limit per group: 5 contributions per tool phase (shown as a nudge, not a hard block)

Minimum viable: Just the logged-in user as a participant is enough to proceed. Everything else can be added later.

Step 4 — Format

This step configures the cycle structure and approval settings.

Movements to include (multi-select, all selected by default):

• ☑ Past
• ☑ Situation
• ☑ Futures
• ☑ Whole (auto-includes, greyed out with tooltip: “The Whole cycle draws from all three movements”)

Approval mode:

Content approval

○ Standard (recommended)
  Student group content is visible within your project immediately.
  You approve before it's shared externally.
  Good for: most classroom situations, when you're also facilitating.

○ Live session mode
  You see uploads in real time and approve as they come in.
  Good for: whiteboard sessions with a co-facilitator.
  
  You can switch between modes at any time during the project.

Group contribution soft limit:

Suggested contributions per group per phase: [5] (editable number)
Groups will see a nudge when they reach this limit.
They can add more, but are encouraged to prioritise first.

International exchange: If a partner institution was selected in Step 1, show:

☑ Enable story interchange with [partner institution name]
  Students will be able to see and respond to each other's 
  approved Present artefacts.

Step 5 — Review

A clean summary of everything configured:

PROJECT
  Name: [name]
  Institution: [institution]
  Partner: [partner or "standalone"]
  
SCHEDULE  
  Format: [format]
  Dates: [start] → [end]
  Sessions: [n] workshop dates

PARTICIPANTS
  Staff: [n]
  Classes: [n] ([total students approx])
  Groups: [n groups suggested]

STRUCTURE
  Movements: Past, Situation, Futures, Whole
  Phases per movement: Gather → Collate → Present
  Total cycle nodes: 12

APPROVAL
  Mode: Standard / Live session
  Group limit: [n] contributions per phase

[ Back ]                    [ Launch Project → ]

Launch Project button:

• Creates all nodes (see Node generation below)
• Shows a brief “Building your project…” animation (just a spinner with the text)
• Navigates to the new project node on completion
• The project node’s content area shows the project dashboard (see below)

Node generation on Launch

The wizard creates the following nodes via the existing PUT /api/nodes/:id endpoint:

Project node:

{
  "id": "proj_[timestamp]",
  "type": "project",
  "title": "[project name]",
  "parent_ids": ["[institution_id]"],
  "relations": [
    { "type": "hosts", "target": "[institution_id]" }
  ],
  "meta": {
    "status": "active",
    "format": "intensive_week|weekly|custom",
    "start_date": "ISO date",
    "end_date": "ISO date",
    "workshop_dates": ["ISO date", ...],
    "academic_calendar": "uk|nz|zambia|custom",
    "approval_mode": "standard|live",
    "group_limit": 5,
    "country_context": "uk|nz|zambia|other"
  }
}

Four movement nodes (Past, Situation, Futures, Whole):

{
  "id": "mov_[proj]_past",
  "type": "cycle",
  "title": "Past",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [
    { "type": "contains", "target": "phase_[proj]_past_gather" },
    { "type": "sequence", "target": "mov_[proj]_situation" },
    { "type": "references", "target": "ref_g_phase" }
  ],
  "meta": {
    "movement": "past",
    "status": "not_started"
  }
}

Twelve phase nodes (3 phases × 4 movements):

{
  "id": "phase_[proj]_past_gather",
  "type": "session",
  "title": "Past — Gather",
  "parent_ids": ["mov_[proj]_past"],
  "relations": [
    { "type": "sequence", "target": "phase_[proj]_past_collate" },
    { "type": "references", "target": "ref_g_phase" }
  ],
  "meta": {
    "movement": "past",
    "phase": "gather",
    "status": "not_started",
    "approval_mode": "standard"
  }
}

The feeds relations for Whole cycle:

{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_past_present" }
{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_situation_present" }
{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_futures_present" }

Person nodes for staff added in Step 3:

{
  "id": "person_[timestamp]",
  "type": "person",
  "title": "[name]",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [{ "type": "involves", "target": "proj_[timestamp]" }],
  "meta": {
    "role": "facilitator|institution_admin",
    "email": "[email]",
    "invite_status": "pending"
  }
}

Class nodes:

{
  "id": "class_[timestamp]",
  "type": "session",
  "title": "[class name]",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [{ "type": "involves", "target": "proj_[timestamp]" }],
  "meta": {
    "student_count": n,
    "suggested_groups": n,
    "teacher_email": "[email]"
  }
}

Project dashboard (post-launch view)

When a project node is selected, its content section shows a project dashboard instead of the standard parents/content/children layout.

The dashboard has two views, toggled by a small tab:

Overview tab (default):

[Project name]                    [Standard mode ▾]  [⚙ Settings]

PROGRESS
Past        [Gather ●●●○○] [Collate ○○○○○] [Present ○○○○○]
Situation   [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]  
Futures     [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]
Whole       [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]

● = contributions uploaded  ○ = empty

NEEDS ATTENTION
  ▶ 3 group contributions awaiting your approval   [Review →]
  ▶ Situation — Gather has no tool selected yet    [Choose tool →]

PARTICIPANTS
  2 staff  ·  1 class  ·  6 groups  ·  ~30 students
  [Manage →]

UPCOMING
  Day 2 — Past Collate    Tomorrow
  Day 3 — Past Present    Thursday

Approval tab (shows when approval_mode is standard):

A list of pending contributions — group name, tool used, phase, timestamp. Each has an Approve and Flag button. Flagged contributions go back to the group with a note.

Live session mode toggle: When switched to live mode, the approval tab becomes a real-time feed — contributions appear as they’re uploaded. A large Approve button dominates. Designed for a facilitator watching a whiteboard.

Navigation changes

In the tree panel:

• Project nodes show a status indicator dot (green = active, grey = not started, amber = needs attention)
• Phase nodes show a progress indicator (e.g. “3 contributions” or “approved”)
• Clicking a phase node navigates to it AND highlights the relevant reference tool nodes in a subtle way (“these tools are available for this phase”)

New project from tree:

• Right-clicking an institution node (or long-press on mobile) shows a context menu: + New Project
• This triggers the same wizard
• Creating a node of type project manually also prompts: “Would you like to use the project setup wizard?” Yes launches wizard pre-filled with the node’s title. No creates a bare node.

What does NOT change

• Existing node structure — unchanged
• Auth system — unchanged
• Reference instance — unchanged
• Tree / position / graph navigation modes — unchanged
• Image maps, temporal nav, quick capture — unchanged
• The standard content view (parents / this node / children) — still available for all nodes including project nodes, accessible via a small “node view” link in the project dashboard

File structure changes

/
├── api/
│   └── projects.js     (new — project creation endpoint that generates full skeleton)
├── lfti-spine.html     (modified — wizard UI, dashboard UI, navigation changes)
└── server.js           (modified — mount projects router)

The project creation logic (generating all 12+ nodes in one transaction) lives in api/projects.js rather than the frontend, so the skeleton is generated atomically server-side. The frontend sends one POST with the wizard data; the server creates all nodes and returns the project id.

POST /api/projects
  body: { name, institution_id, format, start_date, end_date, 
          workshop_dates, movements, approval_mode, group_limit,
          staff, classes, partner_institution_id }
  response: { project_id, nodes_created: n }

When you’re done

Test these five things:

1. Log in as ukadmin@lfti.dev. Select the UK Schools institution node. See the dominant “Start Your First Project” button. Click it. The wizard opens.

2. Complete the wizard with minimal input (just accept all defaults, click Next through each step). Click Launch Project. A project node appears in the tree under UK Schools with 4 movement nodes and 12 phase nodes as children.

3. The project dashboard loads showing the progress grid (all empty), no needs-attention items, and the participant count.

4. Log in as student1@lfti.dev in another browser. Navigate to the new project. Can see the project and its cycle structure. Cannot see the approval tab. Cannot delete anything.

5. Log in as facilitator@lfti.dev. Navigate to a phase node (e.g. Past — Gather). See a nudge toward the reference tool library for that phase (“Browse Gather tools →” linking to the reference Gather Phase node).

← All notes · More from LFTI