Skip to main content

​
Overview

Polaris IDE uses Convex as its real-time database. The schema defines five main tables that handle user management, project storage, file systems, conversations, and AI-generated events.

​
Schema Constants

​
FREE_PROJECT_LIMIT
number
default:"10"
Maximum number of projects allowed for free tier users
​
TRIAL_DAYS
number
default:"7"
Number of days for pro tier trial period

​
Tables Overview

​
Users

Stores user authentication data, subscription status, and project limits. See Users Table for details. Indexes:
  • by_stack_user - Query users by Stack Auth user ID
  • by_clerk - Legacy index for Clerk migration period
  • by_autumn_customer - Query users by Autumn billing customer ID

​
Projects

Manages user projects with import/export status tracking. See Projects Table for details. Indexes:
  • by_owner - Query projects by owner’s Stack Auth ID
  • by_user - Query projects by Convex user document ID

​
Files

Hierarchical file system with support for text files and binary storage. See Files Table for details. Indexes:
  • by_project - Query all files in a project
  • by_parent - Query children of a folder
  • by_project_parent - Composite index for folder contents

​
Conversations

Chat conversations linked to projects for AI interactions. Indexes:
  • by_project - Query all conversations in a project

​
Messages

Individual chat messages with AI tool call tracking. Indexes:
  • by_conversation - Query messages in a conversation
  • by_project_status - Query messages by project and status

​
Generation Events

Tracks AI code generation events with timestamps. Indexes:
  • by_project_created_at - Query events chronologically per project

​
Relationships Diagram

┌─────────────┐
│   Users     │
│ stackUserId │
└──────┬──────┘
       │
       │ ownerId
       │
┌──────▼──────┐
│  Projects   │
│   userId    │──────┐
└──────┬──────┘      │
       │             │
       │ projectId   │ projectId
       │             │
┌──────▼──────┐  ┌───▼────────────┐
│   Files     │  │ Conversations  │
│  parentId   │  └───┬────────────┘
└─────────────┘      │
                     │ conversationId
                     │
                ┌────▼─────────┐
                │   Messages   │
                │  toolCalls   │
                └──────────────┘

┌─────────────────┐
│ Generation      │
│ Events          │
│ projectId       │
└─────────────────┘

​
Schema Definition

The complete schema is defined in convex/schema.ts: 
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export const FREE_PROJECT_LIMIT = 10;
export const TRIAL_DAYS = 7;

export default defineSchema({
  users: defineTable({ /* ... */ })
    .index("by_stack_user", ["stackUserId"])
    .index("by_clerk", ["clerkId"])
    .index("by_autumn_customer", ["autumnCustomerId"]),
  
  projects: defineTable({ /* ... */ })
    .index("by_owner", ["ownerId"])
    .index("by_user", ["userId"]),
  
  files: defineTable({ /* ... */ })
    .index("by_project", ["projectId"])
    .index("by_parent", ["parentId"])
    .index("by_project_parent", ["projectId", "parentId"]),
  
  conversations: defineTable({ /* ... */ })
    .index("by_project", ["projectId"]),
  
  messages: defineTable({ /* ... */ })
    .index("by_conversation", ["conversationId"])
    .index("by_project_status", ["projectId", "status"]),
  
  generationEvents: defineTable({ /* ... */ })
    .index("by_project_created_at", ["projectId", "createdAt"]),
});

​
Authentication

All database operations require authentication via Stack Auth: 
import { verifyAuth } from './auth';

export const myQuery = query({
  args: {},
  handler: async (ctx) => {
    const identity = await verifyAuth(ctx);
    // identity.subject contains the Stack Auth user ID
    // ...
  },
});

​
Best Practices

Always use verifyAuth() at the start of every query and mutation to ensure proper authentication.
Leverage database indexes for efficient queries. Use composite indexes like by_project_parent for common query patterns.
The clerkId field in users table is legacy and maintained only during the migration period from Clerk to Stack Auth.

Build docs developers (and LLMs) love

Get started for freeTalk to us