Database Schema

Overview of MongoDB schemas for links, click events, domains, users, and organizations.

Database Schema & Data Models

GoLink is backed by MongoDB using Mongoose ODM. The schema is engineered for high write throughput, rapid key-value redirection lookups, and compound index aggregation for analytics queries.

1. Link Model (`Link`)

Stores shortened link records scoped to an organization and user.

models/link.schema.ts
const linkSchema = new Schema(
    {
        organizationId: { type: String, required: true },
        domain: { type: String, required: true },
        userId: { type: Schema.Types.ObjectId, ref: "User", required: true },
        shortLink: { type: String, required: true },
        url: { type: String, required: true },
        active: { type: Boolean, default: true },
    },
    { timestamps: true }
);
 
// Indexes
linkSchema.index({ domain: 1, shortLink: 1 });
linkSchema.index({ organizationId: 1, createdAt: -1 });

Key Fields & Indexes

{ domain, shortLink }: Compound unique index enabling O(1) redirection lookup across both custom and default domains.
organizationId: Scopes link queries to the active dashboard workspace.
active: Boolean flag allowing instant pausing without deleting historical records.

2. Click Event Model (`ClickEvent`)

Captures immutable telemetry data whenever a redirect occurs.

models/click-event.schema.ts
const clickEventSchema = new Schema(
    {
        organizationId: { type: String, required: true, index: true },
        linkId: { type: String, index: true },
        gclid: { type: String, required: true, unique: true, index: true },
 
        // Visitor Identity
        visitorId: { type: String, required: true, index: true },
        isNewVisitor: { type: Boolean, default: false, index: true },
 
        // Device Information
        device: {
            type: {
                type: String,
                enum: ["desktop", "mobile", "tablet", "unknown"],
                default: "unknown",
            },
            browser: { type: String },
            os: { type: String },
        },
 
        // Geographic Details
        geo: {
            country: { type: String },
            city: { type: String },
        },
 
        // Referrer & Attribution
        referrer: {
            raw: { type: String },
            domain: { type: String, default: "Direct" },
            source: { type: String, default: "Direct", index: true },
            utmSource: { type: String },
            utmMedium: { type: String },
            utmCampaign: { type: String },
        },
 
        // Request Details
        ip: { type: String },
        userAgent: { type: String },
        isBot: { type: Boolean, default: false },
    },
    { timestamps: true }
);
 
// TTL Index: automatic 90-day retention
clickEventSchema.index({ createdAt: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 90 });

3. Domain Model (`Domain`)

Manages custom branded hostnames registered to an organization.

models/domain.schema.ts
const domainSchema = new Schema(
    {
        organizationId: { type: String, required: true, index: true },
        domain: {
            type: String,
            required: true,
            unique: true,
            lowercase: true,
            trim: true,
            index: true,
        },
        verified: { type: Boolean, default: false },
        primary: { type: Boolean, default: false },
    },
    { timestamps: true }
);

4. Organization & Membership Models

GoLink organizes teams into organizations:

Org: Represents a workspace with an owner, name, and unique URL slug.
Member: Connects a User to an Org with specific permission roles (Owner, Admin, Member).
User: Core user authentication record managed via Better Auth.

Last updated on October 20, 2026

LLMs Support

Links API