Backend

Art demo application walk through

Purpose of this chapter is to show example of working backend for simple application. In our case it’s art management application where user can create artwork, tag it and add to collection together with other artworks.

Overview

The application consist of three sub-projects.

• frontend - located in apps/ui which we will talk about in other chapter.

• server - located in apps/art contain web service and environmental related parts.

• library - located in libs/art-gen contain model definition and set of functions for data flow management.

To reduce necessary to generate multiple web parts in case of many model-oriented libraries we decide to make it relative small. Thanks to that our art application can aggregate domain-specific libraries as part of common web component. Regarding to this we will focus more on apps/art-gen content which contain bigger part of the implementation.

Model

Resolvers, services, mappers, and other automatically generated parts have been created mostly based on the model defined in art.module.ts This means that default implementation for actions like save() or delete() can be adjusted very quickly in case of models structure change by calling again logosphere/sdk:api generator.

If we remove for a while annotations and properties meta-data, the model which we used in the application looks like the following:

class ArtTag 
  name: string;
}

class Art {
  name: string;
  nft: string;
  url: string;
  prop: string;
  tags: ArtTag[];
}

class User {
  username: string;
}

class ArtCollection {
  name: string;
  description: string;
  owner: User;
  arts: Art[];
}

ArtCollection is a main model class. It contains references to User and collection of arts. Art between other contain property nft which stores blockchain minting transaction id and url to IPFS uploaded image. The prop property is to store dynamic fields in JSON format.

The idea behind the tags is to allow a user to find similar artworks by searching keywords they have been marked. Tags are unique and stored permanently. It’s meat that any Art can be tagged by any Tag. Referring to the example below, searching by green, you should get a list of art that has green eyes or hairs. Combining together different keywords, you are able to check how much artwork you would like to mint is similar to other already minted (or pretended to mint) NFTs.

Full-text search is a pretty “heavy” operation. In the case of the production environment, we would rather like to use a third-party engine for that, but for the purpose of our demo, we made UI as our pseudo-engine. During the first load, UI load all tags to local storage to filter them later during typing the tags. If searched phrase already exists, then Art can be referenced with it. Otherwise, a user should create a new unique ArtTag

Structure

This section is to understand a bit better what the contents of the applications and sub-folders are responsible for. If you are familiar with NX, Fluree, GraphQL, NestJS, and their specific concepts, feel free to omit them.

/libs/art-gen/src/canonical/ - Contain fluree schema representation in general (canonical) format. This kind of definition could be used by third-party mappers to move schema between different database engines.

/libs/art-gen/src/dto/ - Input/Output model for service integration. Your services (for example, UI) should stick to this model with requests and responses.

/libs/art-gen/src/entities/ - Fluree schema structure representation included default properties.

/libs/art-gen/src/fluree/ - Contain generated fluree schema. art-fluree-schema-transact.json file can be used in case of manual ledger creation. art-fluree-schema.json is used in main.ts to create a ledger automatically during server start.

/libs/art-gen/src/gql/ - All graphql mutations and queries that have not been generated, need to be added here together with types and inputs

/libs/art-gen/src/mappers/ - Are used in the process of conversion between dtos, entities, and fluree native responses. We decide to keep layer-related models to stick to DDD.

/libs/art-gen/src/repositories/ - Fluree queries and transaction-related logic

/libs/art-gen/src/resolvers/ - GraphQL query and mutation handlers.

/apps/art/src/main.ts - You can define here which file needs to be used to generate fluree schema, change application port, and NestJS-related web parameters like logger.

/apps/art/src/app/app.module.ts - Main point to import libraries and application dependencies. Notice that ArtModule is already part of imports. GraphQL definition can be also adjusted here.

./env - Contain set of environment properties used across all applications and libraries

docker-compose.yaml - Preconfigured stack of services required to works with Cardano blockchain. It include also art application so you can decide if you would like to run the app on docker, or run it manually as from local resource.