Developer Docs

Models

Generated from the Mongoose schemas in apps/api/src/models.

Generated from Mongoose schemas in apps/api/src/models. Field notes come from comments inside the schema where they exist.

Mongoose models

model

Account

Collection: accounts
Timestamps: true

Field	Type	Rules
`userId`	`Schema.Types.ObjectId`	required: true, ref: 'User'
`type`	`String`	required: true
`provider`	`String`	required: true
`providerAccountId`	`String`	required: true
`refresh_token`	`String`
`access_token`	`String`
`expires_at`	`Number`
`token_type`	`String`
`scope`	`String`
`id_token`	`String`
`session_state`	`String`

Indexes{ provider: 1, providerAccountId: 1 }, { unique: true }{ userId: 1 }

apps/api/src/models/Account.ts:3

model

Baseline

Collection: baselines
Timestamps: true

Field	Type	Rules	Notes
`url`	`String`	required: true
`path`	`String`		URL pathname (host-independent). Used to match baselines against a PR's Vercel preview, which lives on a different host than the suite baseUrl. Backfilled lazily — older baselines may only have `url`.
`viewport`	`String`	required: true
`filePath`	`String`	required: true
`isApproved`	`Boolean`	default: false
`currentVersion`	`Number`	default: null	Denormalised pointer to the latest BaselineVersion for this (testSuiteId, path, viewport). Additive — lets the run processor read the "current" baseline without a version lookup. Backfilled on each promote.
`currentVersionId`	`Schema.Types.ObjectId`	default: null, ref: 'BaselineVersion'
`testSuiteId`	`Schema.Types.ObjectId`	required: true, ref: 'TestSuite'

Indexes{ testSuiteId: 1, url: 1, viewport: 1 }, { unique: true }{ testSuiteId: 1, path: 1, viewport: 1 }

apps/api/src/models/Baseline.ts:3

model

BaselineVersion

Collection: baseline_versions
Timestamps: true

Field	Type	Rules	Notes
`testSuiteId`	`Schema.Types.ObjectId`	required: true, ref: 'TestSuite'
`path`	`String`	required: true, trim: true	Host-independent path — canonical page identity (matches SitePage.path).
`url`	`String`	required: true	Canonical URL on the suite origin at approval time.
`viewport`	`String`	required: true
`version`	`Number`	required: true	Monotonic per (testSuiteId, path, viewport), starting at 1.
`filePath`	`String`	required: true	S3/CloudFront URL of the approved screenshot.
`source`	`String`	required: true, enum: Object.values(BaselineSource)
`approvedBy`	`Schema.Types.ObjectId`	default: null, ref: 'User'	Reviewer who approved this version; null for auto-seeded/legacy entries.
`approvedAt`	`Date`	required: true, default: Date.now
`testRunId`	`Schema.Types.ObjectId`	default: null, ref: 'TestRun'	Run the screenshot came from, when applicable.
`pageResultId`	`Schema.Types.ObjectId`	default: null, ref: 'PageResult'	The specific page result promoted, when applicable.
`diffScore`	`Number`	default: null	Diff % versus the version it replaced (null for the first version).
`prNumber`	`Number`	default: null	Set when source === PR_MERGE.
`note`	`String`	default: null	Optional reviewer note.

Indexes{ testSuiteId: 1, path: 1, viewport: 1, version: -1 }, { unique: true }{ testSuiteId: 1, path: 1, approvedAt: -1 }

apps/api/src/models/BaselineVersion.ts:16

model

GitHubInstallation

Collection: github_installations
Timestamps: true

Field	Type	Rules	Notes
`installationId`	`Number`	required: true, unique: true
`accountLogin`	`String`	required: true
`accountType`	`String`
`repos`	`[String]`	default: []	Full names ("owner/repo") this installation can access, when known.

apps/api/src/models/GitHubInstallation.ts:8

model

PageResult

Collection: page_results
Timestamps: true

Field	Type	Rules	Notes
`url`	`String`	required: true
`path`	`String`		URL pathname, used to promote PR images to baselines by path.
`viewport`	`String`	required: true
`status`	`String`	required: true, default: ResultStatus.PENDING, enum: Object.values(ResultStatus)
`approved`	`Boolean`	default: false	Set true when a reviewer approves this result's image (PR runs).
`approvedBy`	`Schema.Types.ObjectId`	default: null, ref: 'User'	Reviewer who approved this result in-app. Recorded at approve time so PR runs can attribute the baseline version when the PR later merges (the merge happens in a webhook with no user session).
`approvedAt`	`Date`	default: null
`isNew`	`Boolean`	default: false	True when no baseline existed for this path/viewport at run time.
`diffScore`	`Number`
`baselineFile`	`String`
`currentFile`	`String`
`diffFile`	`String`
`error`	`String`		Detailed error message when status is ERROR.
`testRunId`	`Schema.Types.ObjectId`	required: true, ref: 'TestRun'

Indexes{ testRunId: 1 }{ status: 1 }

apps/api/src/models/PageResult.ts:6

model

PasswordResetToken

Collection: password_reset_tokens
Timestamps: { createdAt: true, updatedAt: false }

Field	Type	Rules
`userId`	`Schema.Types.ObjectId`	required: true, ref: 'User'
`token`	`String`	required: true, unique: true
`expires`	`Date`	required: true

Indexes{ expires: 1 }, { expireAfterSeconds: 0 }{ userId: 1 }

apps/api/src/models/PasswordResetToken.ts:3

model

SitePage

Collection: site_pages
Timestamps: true

Field	Type	Rules	Notes
`testSuiteId`	`Schema.Types.ObjectId`	required: true, ref: 'TestSuite'
`url`	`String`	required: true, trim: true	Full URL on the suite's own host.
`path`	`String`	required: true, trim: true	Host-independent pathname + search — canonical page identity.
`title`	`String`	default: null, trim: true	<title> captured during discovery, when available.
`status`	`String`	default: PageStatus.ACTIVE, enum: Object.values(PageStatus)
`tracked`	`Boolean`	default: false	Selected for visual diffing.
`firstSeenAt`	`Date`	required: true, default: Date.now
`lastSeenAt`	`Date`	required: true, default: Date.now
`removedAt`	`Date`	default: null	Set when the page goes missing from a crawl (status === REMOVED).

Indexes{ testSuiteId: 1, path: 1 }, { unique: true }{ testSuiteId: 1, tracked: 1 }{ testSuiteId: 1, status: 1 }

apps/api/src/models/SitePage.ts:13

model

TestRun

Collection: test_runs
Timestamps: true

Field	Type	Rules	Notes
`status`	`String`	required: true, default: RunStatus.PENDING, enum: Object.values(RunStatus)
`runType`	`String`	required: true, default: RunType.MANUAL, enum: Object.values(RunType)	What triggered this run.
`git`	`Schema.Types.Mixed`	default: null	Git/PR context for PR and BRANCH runs. Shape: { prNumber?, headSha?, branch?, baseBranch?, previewUrl?, checkRunId?, installationId? } — see TestRunGitContext in @viz/types.
`reviewState`	`String`	required: true, default: VisualReviewState.NOT_REQUIRED, enum: Object.values(VisualReviewState)	Visual review gate state (drives the GitHub check for PR runs).
`startedAt`	`Date`	default: Date.now
`endedAt`	`Date`
`metadata`	`Schema.Types.Mixed`
`testSuiteId`	`Schema.Types.ObjectId`	required: true, ref: 'TestSuite'

Indexes{ testSuiteId: 1, createdAt: -1 }{ status: 1 }{ testSuiteId: 1, 'git.prNumber': 1 }{ 'git.headSha': 1 }

apps/api/src/models/TestRun.ts:6

model

TestRunLog

Collection: test_run_logs
Timestamps: true

Field	Type	Rules
`type`	`String`	required: true, enum: Object.values(LogType)
`message`	`String`	required: true
`metadata`	`Schema.Types.Mixed`
`timestamp`	`Date`	required: true
`testRunId`	`Schema.Types.ObjectId`	required: true, ref: 'TestRun'

Indexes{ testRunId: 1, timestamp: 1 }{ type: 1 }

apps/api/src/models/TestRunLog.ts:6

model

TestSuite

Collection: test_suites
Timestamps: true

Field	Type	Rules	Notes
`name`	`String`	required: true, trim: true
`baseUrl`	`String`	required: true, trim: true
`description`	`String`	trim: true
`kind`	`String`	required: true, default: TestSuiteKind.SUITE, enum: Object.values(TestSuiteKind)	SUITE (default) for crawl-based suites; MANUAL for lightweight single-URL quick-test buckets that skip discovery. See TestSuiteKind in @viz/types.
`config`	`Schema.Types.Mixed`	required: true
`isActive`	`Boolean`	default: true
`github`	`Schema.Types.Mixed`	default: null	Linked GitHub repo enabling PR visual-regression checks. Shape: { owner, repo, installationId, checkContext? } — see TestSuiteGitHubLink in @viz/types. Stored as Mixed so it can be null.
`crawl`	`Schema.Types.Mixed`	default: () => ({ status: 'IDLE' })	Site-discovery crawl state — see SuiteCrawlState in @viz/types. Shape: { status, lastCrawledAt?, lastStats?: { pagesFound, pagesAdded, pagesRemoved }, error? }. Stored as Mixed for flexibility.
`userId`	`Schema.Types.ObjectId`	required: true, ref: 'User'

Indexes{ userId: 1, isActive: 1 }{ createdAt: -1 }{ kind: 1, createdAt: -1 }{ 'github.owner': 1, 'github.repo': 1 }

apps/api/src/models/TestSuite.ts:6

model

User

Collection: users
Timestamps: true

Field	Type	Rules
`email`	`String`	unique: true, trim: true
`emailVerified`	`Date`	default: null
`password`	`String`
`name`	`String`	trim: true
`image`	`String`

apps/api/src/models/User.ts:3