From 8a7d7710be305bd3e2ba274ef4980451a5ddeaf2 Mon Sep 17 00:00:00 2001 From: Somnath Prasad Date: Wed, 23 Jun 2021 21:59:43 +0530 Subject: [PATCH 1/2] docs(versioned_docs/version-0.22): add high-level-architecture.md - #275 --- website/i18n/en.json | 12 +++++++ .../version-0.22/high-level-architecture.md | 33 +++++++++++++++++++ .../version-0.22-sidebars.json | 1 + 3 files changed, 46 insertions(+) create mode 100644 website/versioned_docs/version-0.22/high-level-architecture.md diff --git a/website/i18n/en.json b/website/i18n/en.json index 3085cba4..72f6397d 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -623,18 +623,30 @@ "version-0.21/version-0.21-tutorial-vscode": { "title": "With VS Code" }, + "version-0.22/version-0.22-high-level-architecture": { + "title": "Concepts and High-level Architecture" + }, "version-0.22/version-0.22-markup-preliminaries": { "title": "Preliminaries" }, "version-0.22/version-0.22-ref-cicero-api": { "title": "Cicero API" }, + "version-0.22/version-0.22-ref-cicero-cli": { + "title": "Command Line" + }, "version-0.22/version-0.22-ref-concerto-api": { "title": "Concerto API" }, + "version-0.22/version-0.22-ref-concerto-cli": { + "title": "Command Line" + }, "version-0.22/version-0.22-ref-ergo-api": { "title": "Ergo API" }, + "version-0.22/version-0.22-ref-ergo-cli": { + "title": "Command Line" + }, "version-0.22/version-0.22-ref-migrate-0.21-0.22": { "title": "Cicero 0.21 to 0.22" }, diff --git a/website/versioned_docs/version-0.22/high-level-architecture.md b/website/versioned_docs/version-0.22/high-level-architecture.md new file mode 100644 index 00000000..c376e4e2 --- /dev/null +++ b/website/versioned_docs/version-0.22/high-level-architecture.md @@ -0,0 +1,33 @@ +--- +id: version-0.22-high-level-architecture +title: Concepts and High-level Architecture +original_id: high-level-architecture +--- + +![](/docs/assets/cicero-spec-overview.png) + +## Step 1: Creation of Clause Template +A legal professional analyzes a contract to determine the frequently used/standard clauses that are present. Clauses that are amenable to automation are extracted into a clause template. The template (more details follow) is comprised of the annotated legal text and an accompanying template data model that defines the assets, participants, concepts and events that are relevant to the clause. The business logic for the clause is coded by a developer (with review and in collaboration with the legal professional, or the suitably trained legal professional can code the contract logic themselves using the [Ergo](https://docs.accordproject.org/docs/0.13/logic-ergo) DSL). + +## Step 2: Data Modeling +Concept Template Data Model. The variables and expressions in a template are expressed in terms of a typed data model, that captures all the concepts of relevance to the clause. The data model technology allows importing concepts from namespaces, allowing concepts to be shared across templates. + +## Step 3: Generation of the Template Parser +The [Cicero Open Source project](https://github.com/accordproject/cicero) contains code that can automatically generate a parser from the annotated template text (template grammar) and the associated template data model. The parser generation is completely automatic and supports customization of types and nested grammars. + +## Step 4: Create a Clause +The generated template parser can now be used to dynamically edit and validate source clause text (potentially using code completion, error reporting etc). The editor technology can be embedded on a webpage, or executed as a SaaS service, or run within an IDE. + +## Concept 5: Clause (instance of a Template) +The output of the Template Parser is an instance of the Template Model (a JSON abstract syntax tree that can be deployed to the engine). It captures a machine readable (and hashable) representation of all the executable data extracted from the clause text. + +## Step 6: Invoke Engine with a Request +The application feeds JSON documents to the engine that represents the request instances, which themselves have been modelled in the Template Data Model. These requests represent events of significance to the clause from the outside world. + +## Step 7: Execute and Return Response +The engine invokes the business logic for the template, passing in the parameterization data, a context object and the incoming request. The engine validates the response and then returns it to the caller. The structure of the response is modelled in the Template Data Model. + +Once a template has been created (Steps 1 to 4), it can be used to instantiate a contract (Step 5) which itself can be executed by the template engine (Steps 5 to 6). Both contract instantiation and execution are shown in greater details on the following figure: +![](/docs/assets/execution_context.png) + +>Note that the Accord Project specification does not assume a specific execution environment. [Cicero](https://github.com/accordproject/cicero), which implements the Accord Project specification, includes a Node.js VM based execution engine for contracts created from Accord Project templates. The engine routes incoming requests to template functions, performs data validation, executes the functions within a sandboxed environment, and then validates the response. It can also update the contract state and emit events and/or contract obligations back to the caller. \ No newline at end of file diff --git a/website/versioned_sidebars/version-0.22-sidebars.json b/website/versioned_sidebars/version-0.22-sidebars.json index 3cafec15..b59bb369 100644 --- a/website/versioned_sidebars/version-0.22-sidebars.json +++ b/website/versioned_sidebars/version-0.22-sidebars.json @@ -13,6 +13,7 @@ "version-0.22-started-resources" ], "Template Guides": [ + "version-0.22-high-level-architecture", { "type": "subcategory", "label": "Markdown Text", From 638985a7955134de8099fc1971fb0aec29c7b3bf Mon Sep 17 00:00:00 2001 From: Somnath Prasad Date: Thu, 24 Jun 2021 20:31:19 +0530 Subject: [PATCH 2/2] add name to all-contributorsrc file --- .all-contributorsrc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.all-contributorsrc b/.all-contributorsrc index a7f6c2d5..bb137459 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -46,6 +46,15 @@ "doc" ] }, + { + "login": "somnathPrasad", + "name": "Somnath Prasad", + "avatar_url": "https://avatars.githubusercontent.com/u/67831321?v=4", + "profile": "https://github.com/somnathPrasad", + "contributions": [ + "doc" + ] + }, { "login": "FelixKuehl", "name": "Felix Kühl",