Feakin Knowledge Language Spec

Fkl provide a two-way binding between design-implementation.

Indesign:

• DDD syntax. DDD strategy and tactic description.
• DomainEvent implementation syntax. for generate implementation of DomainEvent.
• Binding syntax. mapping DSL to SourceCode
• Layered syntax. layered structured syntax.
• Description syntax. description design in fake code.

TBD:

• Typedef (TBD). for DDD syntax type bootstrapping.
• Style (TBD). for design visualization UI.

DDD

DDD Syntax:

| decl | | usage | |--------------------|--------|------------------------------------------------------------------------------| | contextmapdecl | : | [ 'ContextMap' ] [ ID ] '{' (contextnodedecl | contextnoderel ) '}' | | | | | attlist | | contextnodedecl | : | ['context'] [ID] | | contextnoderel | : | [ ID ] relsymbol [ ID ] | | relsymbol | : | ('->' | '<-' | '<->') |
| contextdecl | : | [ 'Context' ] [ ID ] '{' aggregatelist? '}' | | | | | attlist | | attlist | : | attritem+ | | attritem | : | ([ ID ] '=' [ value ] ','?)* ';'? | | | | | ([ ID ] ':' [ value ] ','?)* ';'? | | | | | [ ID ] ([ value, ',' ])* ';'? | | aggregatedecl | : | [ 'Aggregate' ] [ ID ] '{' entitylist '}' | | | | | attlist | | entitydecl | : | [ 'Entity' ] [ ID ] '{' valueobjectlist '}' | | | | | attlist | | valueobjectdecl | : | [ 'ValueObject' ] [ ID ] '{' valuelist '}' | | | | | att_list |

Sample

```kotlin ContextMap Ticket {}

Context ShoppingCarContext {}

// render wtih UML styled? Aggregate Cart { """ inline doc sample just-demo for test """ display = "Cart"; DomainEvent CartCreated, CartItemAdded, CartItemRemoved, CartItemQuantityChanged, CartCheckedOut; DomainEvent CartItemQuantityChanged;

// Concept or UML like ? // can be inside or outside of the Aggregate Entity Cart { // it's to many, can change in different way. ValueObject CartId ValueObject CartStatus ValueObject CartItem ValueObject CartItemQuantity ValueObject CartItemPrice ValueObject CartItemTotal ValueObject CartTotal } }

// global detail for Cart. Entity Cart {}

DomainLanguage(sourceSet = TicketLang) ```

DomainEvent Implementation

Subscribe / Publish / Event / Flow

Default impl config

kotlin default impl { techstack { language = "Kotlin" framework = "Spring" message = "Kafka" dao = "JPA" cache = "Redis" search = "ElasticSearch" } }

API

• input -> request
  • pre-validate
• output -> response
  • post-validate
• process -> flow
  • tasking

compare to given-when-then.

```kotlin impl CinemaCreated { endpoint { POST "${uri}/post"; contentType: application/json; authorization: Basic {{username}} {{password}}; request { "id": {{$uuid}}, "price": {{$randomInt}}, "ts": {{$timestamp}}, "value": "content" } expect { "status": 200 "data": { "id": {{$uuid}}, "price": {{$randomInt}}, "ts": {{$timestamp}}, "value": "content" } }; }

// created in ApplicationService flow { via UserRepository::getUserById receive user: User // send "book.created" to Kafka via UserRepository::save with parameter() ?? // or via UserRepository::save(user: User) receive user: User; // message queue via MessageQueue send CinemaCreated to "CinemaCreated" // http request via HTTP::post (with parameter())? to "${uri}/post" // grpc Greeter via GRPC::Greeter send CinemaCreated to "CinemaCreated" // map filter choose(isUserValid) { is true => { // do something } is false => { // do something } } }

validate { pre {

}
post {

}

} } ```

```java // getuserbyuserid from JPA public User getUserByUserId(String userId) { return userRepository.findByUserId(userId); }

// getuserbyuserid from MyBatis public User getUserByUserId(String userId) { return userMapper.getUserByUserId(userId); } ```

```kotlin impl CinemaCreated { """bla bla""" // or binding to ? // binding: aggregate().

// location with modules // default to "root" or ":" target: "${DomainObject}:com.example.book" // ? qualified: "${moduleName}:com.example.book",

endpoint { // message map notication ? // RPC API // HTTP API ? host: "http://localhost:8080" url: "/api/v1/books"

method: "POST"  

test {
   host: ""
   token: ""
}

}

entity: Book input CreateBookRequest { struct { "title" : "string", "author" : "string", "price" : "number" } example { "title" : "The Lord of the Rings", "author" : "J.R.R. Tolkien", "price" : 29.99 } validate { // title.length > 10 ? title { required { min: 3, max: 10 } pattern { regex: "^[a-zA-Z0-9]+$" } range { min: 1, max: 100 } } } }

middle { via User get/update/delete/post userId via Kafka send "book.created" // send "book.created" to Kafka }

output CreateBookResponse { struct { "id" : "number" } validate { } }

// contract-based development output CreateBookResponse(xpath=""); input CreateBookResponse(sourceSet="PetSwagger" location=""); } ```

Binding

binding source code to Context Map

``` Context Ticket {

}

binding Ticket { language: "Kotlin", layered: DDDLayered, qualified: "${moduleName}:se.citerus.dddsample.domain.model", // equals moduleName: "domain" package: "se.citerus.dddsample.domain.model" } ```

SourceSet

SourceSet is design for support 3rd-party dsl, like PlantUML, Swagger.yaml

| decl | | usage | |------------------------|--------|-----------------------------------------| | sourcesetdecl | : | simplesourcesetdecl | | | | | spacesourcesetdecl | | spacesourcesetdecl | : | [ 'SourceSet' ] [ ID ] '{' attlist '}' | | simplesourcesetdecl | : | [ 'SourceSet' ] [ ID ] '(' attlist ')' | | implementationdecl | : | [ 'impl' ] [ID] '{' (inlinedoc) '}' |

PlantUML for Structure

file_type: uml, puml

``` Struct(sourceSet=DddUml, location="")

SourceSet DddUml { type: "puml", file: PlantUml }

// or SourceSet(type="puml", file="ddd.puml") ```

Swagger API

file_type: Yaml, JSON

with: XPath

refs:

• xpath syntax: https://github.com/antlr/grammars-v4/blob/master/xpath/xpath31/XPath31.g4

SourceSet PetSwagger { file: "openapi.yaml", type: OpenApi, prefix: "Pet" // add prefix to items }

UniqueLanguage model ?

file_type: CSV, JSON, Markdown ?

SourceSet TicketLang { file: "ticket.csv", type: UniqueLanguage, // or also for UL prefix: "Ticket" }

Layered

Layered is design for decl

| decl | | usage | |------------------|--------|-------------------------------------------------------------| | layereddecl | : | 'layered' ([ ID ] | 'default' ) '{' layeredbody? '}' | | layeredbody | : | layerdependency | | | | | layeritemdecl | | layeritemdecl | : | 'layer' [ ID ] '{' layeritementry* '}' | | layeritementry | : | packagedecl | | packagedecl | : | 'package' ':' [ string ] |

kotlin layered default { dependency { "interface" -> "application" "interface" -> "domain" "domain" -> "application" "application" -> "infrastructure" "interface" -> "infrastructure" } layer interface { package: "com.example.book" } layer domain { package: "com.example.domain" } layer application { package: "com.example.application" } layer infrastructure { package: "com.example.infrastructure" } }

Description

Description can provide design in fake code way.

Description Syntax:

| decl | | usage | |------------------|--------|-------------------------------------------------------------------------| | descriptiondecl | : | [ ID ] '{' expr* '}' | | expr | : | ifexpr | | | | | chooseexpr | | | | | behaviorexpr | | ifexpr | : | [ 'if' ] '(' [ expression ] ')' | | chooseexpr | : | [ 'choose' ] '(' [ expression ] ')' | | behavior_expr | : | ['via'] [ ID ] action [ID] | | action | : | [ 'get' | 'update' | 'delete' | 'create' | 'send'] |

```kotlin description FakeCode { if (and ?) then {} else {} choose() { condition: condition: }

done operator: <, >, >=, <=, ==, +, -, *, %, /, ? // call via Entity send/ receive Event; } ```

Typedef (TBD)

Typedef provide custom syntax like container or others, can support for bootstrapping DDD syntax.

BuildIn Types

| Name | Description | |-------------|---------------------------------| | identifier | unique identifier | | binary | Any binary data | | bits | A set of bits or flags | | boolean | "true" or "false" | | enumeration | Enumerated strings | | string | string | | number | Any number, can be float or int | | optional ? | Optional type ? |

Container

```groovy typedef(container) ContextMap {

} ```

| decl | | usage | |--------------|-----|-------------------------------------------------------| | typedefdecl | : | [ 'typedef'] '(' metaType ')' ID '{' (decllist) '}'; | | decllist | : | declitem* | | declitem | : | [ID] ':' declname |

Style Decl (TBD)

```kotlin styles {

// node
element "Software System" {
    background #1168bd
    color #ffffff
}
element "Person" {
    shape person
    background #08427b
    color #ffffff
}

// edge
relationship <tag> {
    thickness <integer>
    color #777777
    colour #777777
    dashed <true|false>
    style <solid|dashed|dotted>
    routing <Direct|Orthogonal|Curved>
    fontSize <integer>
    width <integer>
    position <integer: 0-100>
    opacity <integer: 0-100>
}

} ```