Architecture guide

The Noun & Verb generator is the engine that enables a superior developer experience.

This sections describes the inner workings of Noun & Verb generator.

But before we do that, we need to understand the giants, on whose shoulders Noun & Verb stands. These are the open-source battle-tested components. Three of them are critical to list both for:

1. understanding the inner workings
2. understanding how Noun & Verb can make a claim of zero-lockin

The Noun & Verb generator really wires up open-source, battle-tested components into a cogent whole. By providing a partitioned structure and generating simple to understand code in small units, Noun & Verb provides a simple yet flexible solution to an otherwise complex problem.

There are three critical components involved. Listed below, is a brief description of their purpose and any special considerations necessary.

Open Source components

Prisma is the most critical piece of Noun & Verb. Each model in the Prisma schema represents a Noun. And the CRUDish API exposed by the Prisma client is mirrored to a GraphQL API specification by Noun & Verb.

GraphQL is another critical piece of Noun & Verb. This is uses to specify an API that is actually exposed to the client.

Noun & Verb uses the combined auto-generated & custom GraphQL specification to generate a server.

Last, but not least, Noun & Verb uses the Apollo GraphQL server as the execution engine for the GraphQL specification.

By default it uses the apollo-server-micro, but this can be customized if so desired.

Wiring it up together

Now that we know what components we use, it's time to dig into what it means to wire it all up together.

Cornerstones

Prisma & GraphQL are the cornerstones of the capability enabled by Noun & Verb.

• Prisma models represent Nouns
• GraphQL Operations represent Verbs

Prisma Client Generator

The prisma generation process invokes all generators listed. prisma-client-js generates a TypeScript client for use on the server. This generates an API that maps directly to the schema and the Database type used. Please see Prisma Client documentation for more details.

USER Noun & Verb Annotations

To realize the full potential of Noun & Verb, we'd need to add annotations to the basic Prisma schema. Please see Noun & Verb annotation documentation for more details

GEN STEP 1: GraphQL API Generation

When the Noun & Verb generator is invoked, the first thing it does is process the prisma schema (actually it's internal representation, called DMMF), and generate a GraphQL spec compliant API that mirrors the Prisma Client.

Noun & Verb uses a deep understanding of the prisma schema (actually, its internal format called DMMF) to do much of its work. Each model in the schema.prisma represents a Noun of the system being operated upon by the API.

The Prisma client exposes a CURDish client for use on the server side. Noun & Verb uses the same DMMF file used by Prisma to mirror this client into a GraphQL API.

Security

Critical to note, that the Prisma client exposes two general purpose methods -

• queryRaw &
• executeRaw.

These allow execution of arbitrary SQL and can be a great security risk. Noun & Verb hides these from the mirrored API, and forces you to define custom verbs. Within custom verbs, you can invoke these methods with a more constrained set of parameters if so desired. Of course, you could also use a sequence of other function calls on the Prisma Client. So you still have all the flexibility, without a needless security headache.

GEN STEP 2: Seeder Script (synthetic data)

Noun & Verb interprets the parsed Gra

USER: Custom Verbs

Custom verbs are typically specified on a second pass of the generator. In the first pass, we'd have create the Prisma Client and the Mirror API. This allows us to have access to the types with @readOnly, @writeOnly, @createOnly & @hidden annotations applied.

One can use these types, to define custom types in GraphQL operations that are named as necessary to represent the domain of the application being developed.

Please see Custom verb documentation for more details.

GEN STEP 3: GraphQL Server

During a Noun & Verb generator pass, all graphQL src/**/*.sdl files found are processed.

This is perhaps the most complex piece of internal machinery that runs on your behalf. Since Noun & Verb is designed to deal with large schemas, a 1:1 file parity is maintained between the .sdl files and corresponding .ts file.

• All GraphQL types are translated into TypeScript types. All type/input/interface/union extensions are collated into the same location as the root definition.
• All GraphQL scalars are translated into a scalar definition (along with an automated test)
• All GraphQL Enums are collated to a single file.
• All GraphQL resolvers are rendered

Once these steps are completed, the filter specification is used to generate individual APIs for each specification found. In the absence of the filter file, a single default API served at /graphql is created with an implied **/* filter.

Flexibility

Out of the gate, Noun & Verb creates a mirror of the Prisma Client as described below. Using Noun & Verb annotations, provides substantial field level control over the exposed API.

While a CURD API is easy to understand, it's also a very powerful tool. It essentially exposes admin level access to a client. This is not desirable in an over-whelming number of use cases.

For example, in an e-commerce application, we'd want to expose product search capabilities to our customers, but restrict access to add new products to our suppliers.

Noun & Verb tackles these challenges by providing three capabilities:

1. An ability to specify custom Verbs, which are just GraphQL operations, but distinct from the CRUD based API exposed by default.
2. An ability to filter out GraphQL operations from an exposed API at an operation level.
3. An ability to compose multiple, filtered APIs to match different stake-holder needs.

These capabilities are exposed via the Noun & Verb annotations and filters.

GEN STEP 4: Automated Tests

Finally, Noun & Verb generates tests for all API calls in the GraphQL specification.

For the mirrored Prisma API, these are integration tests, in that they exercise the GraphQL API with mock data using the same generators as used to generate seed data in Step 2 above.

For custom verbs, the test scaffolding is generated. One only has to provide the right mock data for the test to be functional. As with everything custom in Noun & Verb, helpful TODO annotations pin-point the location by file:line-number.