​
Introduction

Novoyager’s codebase is set up in a monorepo (via Turborepo) and is closed-source. Here’s the monorepo structure: 
apps
├── api
├── docs
├── web
packages
├── eslint-config
├── typescript-config
The apps directory contains the code for:
  • web: The frontend of the Novoyager’s application
  • api: Novoyager’s FastAPI backend - written in Python
  • docs: Novoyager’s documentation site
The packages directory contains the code for:
  • eslint-config: ESLint configurations for Novoyager’s codebase. Boilerplate code included as part of the create Turbo command
  • typescript-config: TypeScript configurations for Novoyager’s codebase. Boilerplate code included as part of the create Turbo command

​
Running Novoyager

​
Step 1: Local setup

Make sure you have PNPM installed. You can install it using npm: 
npm install -g pnpm
Make sure you have Poetry installed. You can install it using pipx: 
pipx install poetry
1

Clone the repo

Clone the Novoyager repo.
git clone https://github.com/css-labs-admin/novoyager.git
2

Install dependencies

Change to the root directory of the cloned repository and install the dependencies using the following command:
cd novoyager
pnpm install
3

Open code-workspace

It is recommended to use the pre-configured Workspace stored in the .vscode folder at the project root.Navigate to novoyager/.vscode/ and double click novoyager.code-workspace to open in VS Code, or, in VS Code navigate to File and then Open Workspace from File.
You can rename this to match your project name. The extension, code-workspace, must stay the same, but it can be changed to novoyager.code-workspace

​
Step 2: Python setup

In a monorepo, VS Code sometimes uses the wrong Python interpreter, leading to module not found errors. You can open the api folder in its own VS Code window, but using the pre-configured Workspace is recommended.
While working on the Python backend, ensure that your terminal is activated in the correct folder. From the root, run the following command to change to the api directory: 
cd apps/api
1

Create a virtual environment

Create a virtual environment in the api directory through poetry:
poetry install
If you’re using Poetry, you could receive an error noting incorrect format of the poetry.lock file. This is a version mismatch between the version installed and the version used to generate the lock file. You can fix this by deleting the poetry.lock file and running poetry install again.
2

Configure .env file

Create a .env file in the api directory and add the following environment variables:
DB_URL=supabase_url
DB_API_KEY=supabase_api_key
DB_EMAIl=email_address
DB_PASSWORD=password

OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GROK_API_KEY=your_grok_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key
PERPLEXITY_API_KEY=your_perplexity_api_key
GROQ_API_KEY=your_groq_api_key
TOGETHERAI_API_KEY=your_togetherai_api_key

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
These can be placeholder values for now, but you’ll need to replace them with your actual Supabase credentials (covered in step 3) as well as all the LLM Keys.

​
Step 3: Creating tables in Supabase

Novoyager uses Supabase as the database for the backend. You’ll need to create a new project in Supabase and then create the required tables. To get this example running, you need to only create two tables in Supabase.
1

Create an account and new project

Visit Supabase and register an account. Once you’re logged in, create a new project and give it a name.
2

Add credentials to `.env`

While your project is building, copy the Project API Key and URL values and add these to the .env file in the api directory, as described in step 3 of the Python setup.
3

Create tables

The tables are seeded with the two .csv files located in the api root, but the tables must be created before seeding.From the dashboard, visit the Table Editor and click the New table button.
Create the users and spells tables with columns that match their respective CSV columns. Below is how they are both configured:
RLS is set to disabled on these tables. Authentication with Supabase was not in the scope for this project, but you will want to configure this yourself for anything more than this simple example. You can read more about RLS in the Supabase documentation.
4

Upload CSV seed data

Once the tables are created, you can seed them with the data from the .csv files. From the Table Editor, click the Insert button and select the relevant .csv file to upload.

​
Step 4: Configure Turbo remote caching (optional)

Turborepo can use a technique known as Remote Caching to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines. By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel.
1

Login via Turborepo CLI

From the project root, run the command: bash npx turbo login This will authenticate the Turborepo CLI with your Vercel account.
2

Link your Turborepo to your Remote Cache

Link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo: bash npx turbo link

​
Step 5: Running everything

To make the most of Turbo’s monorepo structure, you can run the frontend, backend and documentation site simultaneously. From the root, run the following command:
root
pnpm run dev
You can still run each separately by running the task directly from the relevant package.json or by running the pnpm run dev command from a terminal activated in the desired target location

​
Working with a monorepo in VS Code

For a better development experience, you can use VS Code Workspaces for the monorepo. This will allow you to run tasks and debug the codebase from a single window, while keeping things more organised. Furthermore, VS Code doesn’t handle Python virtual environments particularly well when working within a monorepo. Running the dev command from the project root can make VS Code use your global Python installation, instead of the .venv created in the api root. By using a Workspace, this alleviates the problem.
For a more detailed guide on setting up a monorepo in VS Code, check out the official Multi-root Workspaces documentation

​
Step 1: Open the monorepo

In the /.vscode/ directory, you’ll find a novoyager.code-workspace file. Open this file in VS Code to open the monorepo Workspace.

Frontend (web) folder open without using the Workspace

​
Step 2: Running tasks

VS Code will try to autodetect tasks from gulp, grunt, npm, and TypeScript project files across all folders in a workspace as well as search for tasks defined in tasks.json files. The location of tasks is indicated by a folder name suffix

Workspace tasks

From the above example, you can see there are several configured tasks with the relevant folder name after the task name.

​
Step 3: Debugging

With multi-root workspaces, VS Code searches across all folders for launch.json debug configuration files and displays them with the folder name as a suffix. Additionally VS Code will also display launch configurations defined in the workspace configuration file.

Run and debug panel

You can still create launch configurations for each individual package in the monorepo and they will populate in the dropdown list automatically.

​
Workspace launch configurations

If you want to create a Workspace level configuration with compound launch, you can edit the novoyager.code-workspace file and add the configurations you wish to launch.
You can also edit the Workspace configuration file via the Command Palette
(Windows: Ctrl + Shift + P) and searching for open workspace config
A compound launch configuration can reference the individual launch configurations by name as long as the names are unique within the workspace, for example: 
{
	"launch": {
		"version": "0.2.0",
		"configurations": [],
		"compounds": [
			{
				"name": "Launch Frontend and Backend",
				"configurations": ["Next.js: Chrome", "Python: FastAPI"]
			}
		]
	}
}
For a more detailed explanation, check out the official documentation

​
Optional: Extensions

​
Next Steps

Turbo config

Configuring Turbo for your monorepo

FastAPI config

Configuring FastAPI

Frontend config

Configuring Next.js

Documentation config

Configuring Mintlify for documentation