NotesGPT Documentation

NotesGPT is built using the following technologies:

• Database & Cloud Functions: Convex
• Framework: Next.js App Router
• LLM & Transcription: Together Inference (using Mixtral and Whisper)
• Embeddings: Together Embeddings for search functionality
• File Storage: Convex File Storage for voice notes
• Vector Search: Convex Vector search
• Authentication: Clerk
• Styling: Tailwind CSS

Use the Convex CLI to push your functions to a deployment.

• To see all available commands: npx convex -h
• To launch the documentation: npx convex docs

To trigger a mutation in a React component, use the useMutation hook. This returns a function that you can call to execute the mutation. You can use it as a 'fire and forget' call or await the returned Promise to access the mutation's result.

const mutation = useMutation(api.functions.myMutationFunction);

function handleButtonPress() {
  // fire and forget, the most common way to use mutations
  mutation({ first: 'Hello!', second: 'me' });

  // OR
  // use the result once the mutation has completed
  mutation({ first: 'Hello!', second: 'me' }).then((result) =>
    console.log(result),
  );
}

To consume a query function in a React component, use the useQuery hook. Pass the function reference from the generated api object and an object containing the required arguments.

const data = useQuery(api.functions.myQueryFunction, {
  first: 10,
  second: 'hello',
});

A mutation function is used to modify data in the database (insert, update, or delete). Like queries, mutations require an args object with validators and a handler. Mutations can also read from the database using ctx.db before performing write operations.

import { mutation } from './_generated/server';
import { v } from 'convex/values';

export const myMutationFunction = mutation({
  // Validators for arguments.
  args: {
    first: v.string(),
    second: v.string(),
  },

  // Function implementation.
  handler: async (ctx, args) => {
    // Insert or modify documents in the database here.
    const message = { body: args.first, author: args.second };
    const id = await ctx.db.insert('messages', message);

    // Optionally, return a value from your mutation.
    return await ctx.db.get(id);
  },
});

To enable Clerk authentication within your Convex backend, you must export a default configuration object containing a providers array. Each provider requires a domain (the Clerk Issuer URL) and an applicationID (which should be set to 'convex').

Ensure the CLERK_ISSUER_URL environment variable is set in your Convex deployment environment.

export default {
  providers: [
    {
      domain: process.env.CLERK_ISSUER_URL,
      applicationID: 'convex',
    },
  ],
};

The utility library provides two functions for date formatting in the en-US locale:

1. getCurrentFormattedDate(): Returns the current date and time formatted as Month Day, Year, Hour:Minute AM/PM (e.g., "July 12, 2026, 10:30 AM").
2. formatTimestamp(timestamp: number): Takes a Unix timestamp (in milliseconds) and returns a string in the format Month Day, Year at Hour:Minute AM/PM (e.g., "July 12, 2026 at 10:30 AM").

When using Convex with Next.js, usePreloadedQueryWithAuth allows you to access the result of a preloaded query on the client immediately, even while the client is still undergoing authentication.

This hook works by returning the server-side preloaded result if the client-side query hasn't loaded yet. It relies on two assumptions:

1. The query only returns null when it is waiting for authentication.
2. The query is always authenticated when called from the server.

It is a wrapper around usePreloadedQuery that uses preloadedQueryResult as a fallback to prevent the UI from seeing null during the auth transition.