generated from coulomb/repo-seed
225 lines
8.6 KiB
Markdown
225 lines
8.6 KiB
Markdown
# 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.
|
|
|