---

Table of Contents

• Overview
  • Short Demos
• Zero to Hero
  • Pre-requisites
  • General Setup
  • API Development Setup
    • Docker Build and Run
• Technical Documentation
  • ERD

Overview

This repository contains a Node.js application that uses Expresses and Apollo Server to create a GraphQL API.

Short Demos

Agent Lab: The following video demonstrates the GraphQL API in action. The API is used to query the database for agents, capabilities, and their related prompts. It allows easy creation of new agents, capabilities, and prompts as well as additional features like per-organization authorization through Clerk.

agent-lab-demo.mp4

Inquiry Builder: The following video demonstrates the GraphQL API in action. The API is used to query the database for inquiry graphs. An inquiry graph is a dictated conversation flows that can be used to generate a conversation between an agent and a user. It allows for stakeholders to get a dynamic conversation flow between a user and an agent to probe for information or insights, while ensuring that the agent stays on tasks, asks the right questions in the right order, and does not miss any important information while still allowing the user and conversation to go off script at certain times depending on the graph.

inquiry-builder-demo.mp4

Zero to Hero

Pre-requisites

• Node.js (version 22.x or later)
• AWS CLI
• Terraform CDKTF
• Docker
• MongoDB

General Setup

The following steps are required to setup the project for local development and deployment.

1. Configure AWS CLI. You can do this with aws configure. If the environment you working with is managed by AWS SSO, you can run aws configure sso. For more on this see AWS CLI Configuration.

2. Enable corepack for pnpm to install the dependencies. You can do this by running the following command:

corepack enable pnpm
corepack use pnpm@latest

3. Download the repository

git clone [email protected]:Magiscribe/Magiscribe-API.git

4. Change directory to the project root

cd Magiscribe-API

5. Run the install script. This will install the dependencies for the API and Infrastructure projects.

pnpm i

API Development Setup

The following steps are required for local development of the API.

1. Check into /app directory

cd app

2. Copy the .env.example file to .env and update the values as needed.

cp .env.example .env

2. Install the dependencies

pnpm install

3. Start the Docker container for the database and Python execution environment.

pnpm docker:up

4. Run the seed script to populate the database with sample data.

pnpm db:import

4. Start the application in development mode

pnpm dev

5. Open the browser and navigate to http://localhost:3000/graphql to access the GraphQL playground.

• Important Note: To bypass Clerk authentication, you can use the following header in the GraphQL playground:

  {
    "Authorization": "Sandbox"
  }

Docker Build and Run

To run the application using Docker, you can run the following command:

docker build -t graphql-api .
docker run -p 3000:3000 graphql-api -e PORT=3000 -d

Technical Documentation

ERD

erDiagram
    User {
        string _id
        date createdAt
        date updatedAt
    }

    Inquiry {
        string[] userId
        object data
        ObjectId[] responses
        date createdAt
        date updatedAt
    }

    InquiryResponse {
        string userId
        object data
        ObjectId threadId
        date createdAt
        date updatedAt
    }

    Collection {
        string name
        date createdAt
        date updatedAt
    }

    Prompt {
        string name
        ObjectId logicalCollection
        string text
        date createdAt
        date updatedAt
    }

    Capability {
        string name
        ObjectId logicalCollection
        string alias
        string llmModel
        string description
        ObjectId[] prompts
        string outputMode
        string subscriptionFilter
        string outputFilter
        date createdAt
        date updatedAt
    }

    Agent {
        string name
        ObjectId logicalCollection
        string description
        object reasoning
        ObjectId[] capabilities
        boolean memoryEnabled
        string subscriptionFilter
        string outputFilter
        date createdAt
        date updatedAt
    }

    Asset {
        string[] owners
        string s3Key
        date createdAt
        date updatedAt
    }

    Thread {
        string subscriptionId
        object[] messages
        date createdAt
        date updatedAt
    }

    Audio {
        string text
        string voiceId
        string s3Key
        date expiresAt
        date createdAt
        date updatedAt
    }

    User ||--o{ Inquiry : "creates"
    User ||--o{ InquiryResponse : "has"
    User ||--o{ Asset : "owns"
    User ||--o{ Thread : "participates in"
    User ||--o{ Audio : "creates"
    Inquiry ||--o{ InquiryResponse : "has"
    InquiryResponse ||--|| Thread : "references"
    Collection ||--o{ Prompt : "contains"
    Collection ||--o{ Capability : "contains"
    Collection ||--o{ Agent : "contains"
    Prompt }|--o{ Capability : "used by"
    Capability }|--o{ Agent : "belongs to"
    Agent ||--o{ Thread : "participates in"
    Thread ||--o{ Message : "contains"

Loading