Journey engine¶

eAkto turns a validated intent into a versioned, deterministic journey. AI proposes structured context; it does not generate executable workflow code.

Workflow selection¶

workflow_mapper.py applies backend compatibility rules:

• marriage-related record updates map to POST_MARRIAGE_RECORD_UPDATE;
• specific non-marriage record corrections map to GOVERNMENT_RECORD_INFORMATION_UPDATE;
• generic conversation, unsupported goals, portal failures, and completed-status claims do not automatically create a journey.

The selected workflow must be present as an active template.

Declarative rule evaluation¶

Rules use validated operators such as:

• equals / not_equals
• contains / not_contains
• in / not_in
• exists / not_exists
• is_empty / is_not_empty
• nested all, any, and none

The evaluator resolves dot-separated fields in a read-only context. It never executes code stored in the database.

WorkflowRule(
    field="intent.mentioned_records",
    operator=RuleOperator.CONTAINS,
    value="NATIONAL_IDENTITY",
)

Dependency ordering¶

Applicable milestones are topologically ordered. A milestone is blocked when:

• it names a dependency not present in the workflow definition;
• its dependency is already blocked; or
• a cycle prevents a valid order.

Within valid dependency order, priority and stable milestone codes provide deterministic ordering.

Journey creation¶

The Personal Engine:

1. verifies that the intent exists and is supported;
2. loads the active workflow template;
3. builds context from intent, redacted document evidence, and assurance;
4. resolves every milestone;
5. persists applicable and skipped milestone snapshots;
6. marks the first applicable milestone CURRENT; and
7. links the journey to its citizen owner.

Creating a journey from the same intent is idempotent: an existing journey is returned.

Progress and answers¶

Only the current applicable milestone can be completed. Submitted answers are stored under:

{
  "milestone_answers": {
    "CONFIRM_REQUESTED_INFORMATION": {
      "target_record": "National ID",
      "requested_change": "Address"
    }
  }
}

Progress is calculated from persisted milestone state:

completed applicable milestones / all applicable milestones × 100

Flutter animates from the previous visual value to the new server percentage; the backend remains the source of truth.

Reevaluation¶

Evidence or context updates can re-run resolution. Previously completed milestones remain completed. Newly applicable steps are inserted into the resolved order, and the first incomplete step becomes current.

This allows a newly uploaded, verified document to remove a redundant preparation step without losing citizen progress.