coordination-engine/INTENT.md

INTENT.md

Project Name

coordination-engine

Purpose

coordination-engine is a generalized framework and runtime for digital coordination as goal- and result-driven communication between multiple interacting parties.

It provides the foundation for building scenario-specific, headless coordination applications by selecting and composing only the relevant concepts from the framework: participants, intended results, payloads, action surfaces, access, notifications, deliveries, interactions, evidence, policies, and adapters.

The core idea is that digital coordination is not primarily about transporting messages from sender to receiver. It is about managing access, enabling interactions, observing evidence, and applying follow-up policies until an intended result is achieved, failed, expired, escalated, or manually closed.

Primary Utility

coordination-engine helps developers and agents build applications that coordinate people, organizations, systems, payloads, and actions across multiple channels and technologies.

It is intended for scenarios such as:

• digital postal delivery
• secure document access
• document and data collection
• AGB / terms acceptance
• contract signing and closing
• invoice and payment collection
• incident acknowledgement
• approval workflows
• onboarding processes
• regulated communication and evidence tracking

The engine should make these scenarios easier to implement by providing reusable coordination primitives instead of requiring every application to reinvent notification logic, delivery tracking, participant state, evidence handling, and follow-up rules.

Strategic Role

coordination-engine is the implementation project for the broader coordination-framework.

It should become a headless coordination runtime that can be embedded into or integrated with specialized applications. These applications may expose their own user interfaces, portals, workflows, APIs, or agent interfaces while relying on coordination-engine for the underlying coordination logic.

The project is strategically positioned between notification systems, workflow engines, document delivery platforms, campaign automation tools, signature systems, payment systems, and evidence/audit infrastructure.

It is not meant to replace all of these systems. Instead, it provides the coordination layer that can orchestrate them through adapters.

Core Principle

A coordination case is successful when its intended result is satisfied, not when messages have merely been sent.

Digital coordination is the controlled arrangement of participants, payloads, access, notifications, deliveries, interactions, and evidence so that intended results can be achieved under uncertainty.

Conceptual Scope

The project revolves around the following core concepts.

CoordinationCase

A goal-directed coordination process initiated by one party to achieve an intended result involving one or more participants.

Participant

An actor involved in the coordination case, such as an initiator, recipient, respondent, signer, payer, approver, delegate, organization, system, agent, or intermediary.

IntendedResult

The result the initiator wants to achieve, such as payload access, valid submission, acceptance, signature, payment, acknowledgement, or completion.

Payload

A meaningful resource involved in coordination, such as a document, contract, invoice, form, payment request, data package, submitted artifact, or receipt.

ActionSurface

The place where participants interact with the case, such as a portal page, app screen, payment page, signature flow, upload form, approval screen, chatbot, API endpoint, or message reply interface.

Notification

An awareness-oriented communication act that prompts attention or action.

Delivery

The controlled availability, access, transfer, retrieval, submission, or consumption of a payload.

Interaction

A meaningful action performed by a participant, system, agent, or intermediary on a payload or action surface.

EvidenceEvent

A normalized observation used to assess progress, uncertainty, success, failure, or required follow-up.

Policy

A rule set that interprets evidence and determines next actions such as waiting, notifying, reminding, retrying, escalating, switching channels, requesting correction, revoking access, closing, or failing.

Intended Architecture Direction

The runtime should be organized around a central coordination-controller supported by specialized controllers and services:

• coordination-controller
• result-controller
• participant-controller
• payload-controller
• access-controller
• notification-controller
• delivery-controller
• interaction-controller
• identity-authority-controller
• evidence-ledger
• policy-engine
• adapter-layer

The architecture should remain headless, API-first, event-aware, and adapter-friendly.

Scenario Composition

The framework should allow scenario-specific applications to use only the concepts they need.

A simple notification-and-access scenario should not need payment, signature, or document-validation functionality.

A contract-signing scenario should be able to select stronger identity, authority, payload-integrity, signature, and evidence requirements.

A payment-collection scenario should be able to integrate invoice payloads, payment action surfaces, payment-provider events, reminders, disputes, and dunning escalation.

This selective composition is central to the project.

Primary Users

The project is intended for:

• developers building coordination applications
• product teams defining communication-heavy business processes
• operations teams monitoring unresolved coordination cases
• compliance and legal stakeholders reviewing evidence
• automation agents creating, inspecting, and updating cases
• integration partners connecting channel, identity, payment, signature, document, CRM, ERP, or messaging systems

Design Priorities

The project should prioritize:

1. Result orientation Model success through intended result satisfaction, not message dispatch.

2. Headless operation Provide APIs and events rather than a fixed UI.

3. Evidence-driven state Preserve observations and derive assessments from evidence.

4. Uncertainty awareness Treat ambiguous states as first-class, especially where channel evidence is weak.

5. Adapter extensibility Support many protocols, systems, and providers through normalized actions and events.

6. Scenario modularity Allow applications to select the relevant subset of concepts.

7. Auditability Explain why a participant or case was marked successful, failed, partial, expired, escalated, or unresolved.

8. Agent-friendliness Provide clear schemas, APIs, events, and state models suitable for automation.

Initial Implementation Focus

The first implementation should prove the core abstraction with a minimal but useful scenario.

Recommended MVP focus:

• create a coordination case
• add multiple participants
• register one payload
• define an intended result
• create participant-specific access grants
• record simulated or real notification events
• record access and interaction evidence
• derive participant-level state
• derive case-level progress
• generate follow-up actions from policy
• close the case based on sufficient evidence

The first real adapters should likely be:

• email adapter
• portal/action-surface adapter
• webhook adapter

Simulated adapters are acceptable for proving the core runtime.

Non-Goals

coordination-engine is not primarily:

• an email sending system
• a newsletter platform
• a campaign marketing tool
• a document management system
• a payment processor
• a signature provider
• a CRM
• an ERP
• a full workflow/BPMN engine
• a legal proof system by default

It may integrate with these systems, but its role is to coordinate result-oriented interaction across them.

Success Criteria

The project is successful when a developer can define a scenario-specific headless coordination application by composing framework concepts and policies, without hardcoding all coordination logic from scratch.

The first useful version should demonstrate:

• multi-participant coordination
• evidence-driven state changes
• distinction between notification, delivery, access, and interaction
• ambiguous or unresolved states
• policy-based follow-up actions
• result-based closure
• traceability from final assessment to evidence events

Guiding Statement

coordination-engine coordinates participants around payloads and action surfaces through notifications, deliveries, interactions, access control, evidence, and policies to achieve intended results under uncertainty.