Devii consists of two containers: the main API server container, and a separate “process runner” which handles background tasks and running process rule jobs. The API server is implemented as a single-process program which runs behind the Web Server Gateway Interface (WSGI) service broker uWSGI, and evaluates each GraphQL query or mutation according to the following process:

Query Evaluation Detail

1. A GraphQL request is submitted to the API endpoint.
   ‍
2. Devii parses the GraphQL and validates it according to the defined schema. Syntax errors are caught at this time, as well as references to invalid types or fields. If the GraphQL is invalid, an error is signaled.
   ‍
3. Devii prepares a query or mutation object to handle the request.
   ‍
4. Devii’s security engine looks for policy rules which allow the query or mutation to proceed. For a query, a rule being present means that the query can proceed, though the rule’s filters may prevent results from being returned; this is not considered an error. For mutations, a rule filter acts as a constraint, and trying to mutate a record that doesn’t match the filter will trigger an error.
   
   In cases where multiple rules may allow a query or mutation to proceed, the rule engine selects the most specific rule: rules for specific roles first, then for role classes, then rules with only one target table, then rules with multiple target tables. If one applicable rule has a filter and the other does not, the rule without the filter is used. If multiple rules with filters are applicable, an error is signalled. (This is a very rare case, and good policy design should prevent it from ever occurring.)
   ‍
5. If the client passed in a filter expression, ordering specifications, or paging instructions (limit and offset), these are applied after any policy rule filters. The filter expression is parsed by the expression parser, and if valid, applied to the query. Invalid expressions trigger an error.
   ‍
6. The query or mutation itself is executed. What happens then depends on the type of operation being executed:
   • In the case of a query, the results are then returned immediately.
   ‍
   • For a mutation, Devii checks if the target table has any process rules which are applicable to this operation. If there are none, the results of the mutation are returned.
   ‍
   • In the case where there are process rules that apply, Devii must determine if they are synchronous or asynchronous processes. Synchronous processes cause Devii to wait for the process result before returning, and in the case where a synchronous process fails (e.g., payment is declined), Devii will fail the transaction and signal an error. The mutation that would otherwise occur is aborted. Synchronous rules should only be used for relatively quick operations, such as financial transactions, where success or failure of the whole mutation depends on the process succeeding or failing.
   ‍
   • Asynchronous rules, on the other hand, can be run independently; Devii will signal the process runner to start the processes, but will not wait for completion, and will return the mutation results immediately. Asynchronous process rules are suitable for longer-running “batch” work, where something needs to be done based on the data that has been added, updated, or removed, but the results are not needed immediately, and the mutation itself can be allowed to complete without the process being finished.