This document contains information regarding repositories and code. Additionally some information on troubleshooting.

• Developer information
  • Project Details
  • Backend
    • Architecture Overview
    • Codebase folder structure
  • Frontend monorepo
    • Codebase folder structure
  • How to setup Staging environment
  • Environment Variables
    • Development
    • Production
  • Infra Services

Project Details

The project consists of 2 main codebases

• Backend repo

  • Built on top of Keystone CMS which allows building APIs and Models very fast and easy and typesafe with TypeScript and GraphQL
  • Prisma ORM as a database driver
  • Qdrant for vector database for semantic search
  • OpenAI - LLM provider
  • Web Sockets with Pusher
  • Node Resque for delayed jobs

• Frontend monorepo

  • web
    • Next.js frontend framework
    • React.js
    • Tailwindcss css framework
    • Mantine.dev React UI components
  • widget
    • Chat widget code for embedding ResolveAI chat widgets into websites
  • packages
    • shared configurations for TypeScript, eslint
    • shared components
    • shared Graphql Queries

Backend

• Architecture Overview

  

• Codebase folder structure:

  • schema - folder contains all models. Creating model automatically updates prisma schema. For production rollout new migrations needs to be generated if schema was updated.
  • services - folder contains implementation of all core modules. Here are important ones
    • Conversation service - handles communication logic and the go to place for adding new chains or agents for handling conversations with clients via widget or chat apps.
    • Messenger - contains implementation of integration with Facebook Messenger all handlers. Underneath utilizes Conversation service to facilitate communication
    • Qdrant - contains implementation of integration with Qdrant Vector store.
    • SemanticSearch - contains implementation of search using Qdrant
    • SendGrid - integration with SendGrid and emails templates
    • Slack - integration with Slack messenger
    • Stripe - integration with Stripe. Payment handlers and subscription update handlers
    • WhatsApp - integration with WhatsApp. Webhook event handlers.
    • Google - integration with Google oAuth and Google Calendar.
    • GPT - collection of Agents and Chains using LangChain or custom implementations for handling LLM operations.
    • Carbon - integration with Carbon
  • rest-routes - folder contains express routers for REST endpoints. Mostly webhook handlers
    • Stripe
    • Carbon
    • Google
    • HealthCheck
    • Instagram
    • Messenger
    • Slack
    • WhatsApp
    • API
  • node-resque - folder contains node-resque worker and queue setup as well as jobs
  • migrations - contains database migrations for production

• oneoffs - this file contains oneoff scripts, mostly data backfills

• keystone - core entrypoint file that provides configuration for KeystoneCMS. GraphQL schema and configuration, storage, auth, session, REST endpoints, Express server and node-resque worker setup.

• Admin console Keystone comes with admin console which can be accessed here https://cms.resolveai.co/ admin credentials can be found in 1Password

• Deployment Process Deploying is pretty straight forward. Railway is connected with GitHub repo so deployment starts right after PR is merged with main branch or any changes on main branch detected. Railway is using zero downtime deployment so that it will only rollover production to new deployment once it confirms that it is operational using health checks.

• Monitoring and Maintenance: There is a HealthCheck worker separate from Railway one that is deployed also on Railway that only job is to monitor health it will trigger a notification to Slack if server is not responsive

• Troubleshooting Guide:

  • Most important notification is when service is down. Which is sent via Slack by healthcheck worker.
  • Additionally there is a handy log explorer provided by Railway. Something that we unfortunately can’t handle at the moment is OpenAI outages.
  • One way to solve this is to find additional LLM service provider, however this will add overhead to configuring AI Agents because models differently behave per provider.
  • Sentry keeps track of errors in production environment

  

• Workflow:

  • Prerequisites
    • PostgreSQL
    • Redis
    • Node.js 18+
    • Yarn
  • Getting started
    • make sure you have prerequisites
    • install packages run yarn command
    • copy env.example to .env file and add environment variables
      • there will be env file provided in 1Password
    • setup your DB using npx prisma db push
      • Navigate to local keystone admin panel to create admin user
      • Create Stripe subscription product (Hobby, Standard, Plus etc) both monthly and annual
      • Create subscription plans in DB by navigating to Keystone Admin similar to the ones created in stripe and make sure to copy stripe id to price ID
    • launch dev environment yarn dev
  • Development workflow
    • When adding new schema/model make sure that you are creating migration at the end of your dev process. For development you don’t need to create migration, it will automatically update database for you, however production needs to have a migration file in place. You can do so by running npx prisma migrate dev
    • Keystone has support for roles and permissions
      • each model and or field on model can have different permission level. More here.
    • Keystone support hooks that trigger before and after model changes. More here.
    • If you want to enable/disable backend as a worker change IS_WORKER value is .env file

Frontend monorepo