Data Model
ShipLens uses PostgreSQL with the pgvector extension. Here's the complete schema and how entities relate.
Entity Relationship
Core Entities
Company
The tenant root. All data is scoped to a company.
| Field | Type | Description |
|---|---|---|
name | string | Company name |
plan | enum | free, starter, business, enterprise |
settings | map | Company-level configuration |
Team
A sub-group within a company.
| Field | Type | Description |
|---|---|---|
name | string | Team name |
company_id | FK | Parent company |
Contributor
An individual team member. May have multiple git identities.
| Field | Type | Description |
|---|---|---|
name | string | Display name |
team_id | FK | Team membership |
last_commit_at | datetime | Most recent commit timestamp |
Contributor Identity
Maps git emails to contributors, handling the common case of developers using different emails.
| Field | Type | Description |
|---|---|---|
email | string | Git commit email |
contributor_id | FK | Linked contributor |
Project
A connected git repository.
| Field | Type | Description |
|---|---|---|
name | string | Repository name |
company_id | FK | Parent company |
architecture_context | text | Crawled project understanding |
Domain
A logical area within a project with assigned criticality.
| Field | Type | Description |
|---|---|---|
name | string | Domain name (e.g., "auth", "payments") |
criticality | enum | critical, high, medium, low, trivial |
project_id | FK | Parent project |
Analysis Entities
Commit Report
The result of LLM analysis for a single commit.
| Field | Type | Description |
|---|---|---|
sha | string | Git commit SHA |
commit_type | enum | feat, fix, refactor, test, docs, chore, style, perf |
summary | text | LLM-generated summary |
areas_affected | list | Domains/areas touched |
complexity | integer (1-5) | Assessed complexity |
impact | integer (1-5) | Assessed impact |
confidence | float | LLM confidence level |
quality_signals | list | Boolean quality indicators |
risk_signals | list | Boolean risk indicators |
slop_dimensions | map | Seven-dimension slop assessment |
slop_index | float | Computed slop index (0–1) |
gaming_flags | list | Detected gaming patterns |
co_authors | list | Co-author metadata (AI detection) |
depth | enum | shallow, standard, deep |
cost_usd | float | LLM cost for this analysis |
lines_added | integer | Lines added |
lines_removed | integer | Lines removed |
files_changed | list | Files modified |
contributor_id | FK | Author |
project_id | FK | Repository |
committed_at | datetime | When the commit was authored |
Commit Score
The scored result, computed from a Commit Report using the scoring engine.
| Field | Type | Description |
|---|---|---|
final_score | float | The 0–10 score |
normalized_core | float | Complexity × Impact, normalized |
effort_bonus | float | Logarithmic effort contribution |
quality_bonus | float | Quality signals contribution |
risk_bonus | float | Risk signals contribution |
version | integer | Scoring engine version (1 or 2) |
config | map | Scoring configuration used |
commit_report_id | FK | Source report |
Intelligence Entities
Weekly Digest
| Field | Type | Description |
|---|---|---|
week_start | date | Monday of the digest week |
week_end | date | Sunday of the digest week |
content | text | LLM-generated digest content |
status | enum | pending, generating, completed, failed |
cost_usd | float | Generation cost |
company_id | FK | Scope: company |
team_id | FK (nullable) | Scope: team (nil = company-wide) |
One-on-One Report
| Field | Type | Description |
|---|---|---|
period | enum | two_weeks, month, quarter |
content | text | LLM-generated report content |
cost_usd | float | Generation cost |
contributor_id | FK | Subject contributor |
Contributor Alert
| Field | Type | Description |
|---|---|---|
alert_type | string | silent_contributor, high_fix_ratio, low_test_discipline |
message | text | Human-readable description |
resolved_at | datetime (nullable) | When resolved (nil = active) |
contributor_id | FK | Affected contributor |