Journey lifecycle¶

A journey is a persisted instance of a versioned workflow. It belongs to one citizen and tracks applicable milestones, answers, progress, and the current valid action.

Create a journey¶

Prerequisites:

• authenticated citizen;
• current high assurance;
• an owned, supported intent;
• active workflow template.

curl -X POST \
  -H "Authorization: Bearer $EAKTO_SESSION" \
  http://localhost:8000/api/v1/journeys/from-intent/INTENT_ID

Creation reads only redacted vault evidence. Calling the endpoint twice for the same intent returns the existing journey.

List and resume journeys¶

GET /journeys returns every owned journey ordered by recent activity. Home displays:

• one active journey overview when status is ACTIVE or BLOCKED;
• all saved journeys in “My journeys,” including completed items; and
• the no-active-journey illustration when no active journey exists.

Flutter persists the active journey ID as a convenience. On restore, it falls back to the server collection if the local reference is missing.

Render a dynamic plan¶

GET /journeys/{id}/plan returns applicable milestones with backend-defined:

• title and description;
• position and status;
• questions, input type, and options;
• required documents;
• vault document code;
• why each document matters; and
• how to add it.

Flutter renders this structure rather than selecting a hardcoded marriage form.

Complete a milestone¶

curl -X POST \
  -H "Authorization: Bearer $EAKTO_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"answers":{"requested_change":"Address"}}' \
  http://localhost:8000/api/v1/journeys/JOURNEY_ID/milestones/MILESTONE_CODE/complete

The backend rejects attempts to:

• complete a step that is not applicable;
• skip ahead;
• complete a milestone that is not current; or
• mutate another citizen’s journey.

Completing an already completed current milestone is idempotent.

Refresh evidence¶

After a document upload, Flutter calls:

POST /api/v1/journeys/{journey_id}/evidence-refresh

The Personal Engine reevaluates the workflow with new redacted evidence and preserves completed milestones.

Complete a journey¶

When no applicable incomplete milestone remains:

• journey status becomes COMPLETED;
• current_milestone_code becomes null;
• progress becomes 100;
• completion time is stored; and
• Flutter clears the active journey reference.

The completed journey remains visible in journey history.