Kosmos Framework

• Overview
• Architecture
• Usage
  • Using traits
  • Using Apollo Tracing
  • Debug with environment variables
• Deployment tips
  • API Gateway logging
• Documentation guidelines
  • Generating HTML docs
  • Writing docs
    • Documenting traits
  • Updating README

Overview

This repository contains the Kosmos application framework.

Architecture

See architecture documentation.

Usage

Pre-requisites

docker
pip
terraform / tflocal wrapper

To run kosmos locally and kick off tests

npm install
cd gremlin
docker compose up -d
cd ../
cd terraform
terraform init
terraform apply --auto-approve
cd ../
npm run debugger
another window: npm run kosmostests

To run Kosmos with a different directory to the default use

npm run start_directory --dir=<DIRECTORY>

Using traits

A full list of available traits may be found at Trait class documentation page.

TODO

Using Apollo Tracing

It is possible to use Apollo Tracing for analysing performance / timeline of GraphQL queries. To enable it, add the following to your application's config.yml:

graphQlTracing: true

IMPORTANT NOTE: Like virtually any debugging tool, Apollo Tracing could harm performance of queries and should be only used during development.

Debug with environment variables

To debug gremlin query use DEBUG_GREMLIN. To log errors with a stack trace use DEBUG_ERROR_TRACE.

Deployment tips

API Gateway logging

When the logging is enabled for the first time it will throw an error about not having the correct permissions. The fix for this is to enable logging on the gateway manually then redeploy the stack. For some reason you need to manually enable it for the account to flag that logging is allowed.

Documentation guidelines

Generating HTML docs

To generate HTML documentation from the code, run:

npm run docs

Writing docs

Inline code documentation is using TypeDoc format. The generator supports following features:

• TypeDoc syntax.
• Using Markdown.
• Embedding code examples with syntax highlighting.
• Diagrams using mermaid.

Documenting traits

The Trait documentation should include:

• Short description of what it's doing.
• YAML usage example.
• UML sequence or other diagrams, if needed.

Good examples are SearchTrait, FileUrlTrait and MembershipTrait.

Updating README

After updating README, run the following command to update table of contents:

npm run toc