Core Architecture & Moats

Mantis Platform Reference & Developer Manual

Mantis is an ultra-fast, enterprise-grade defect monitoring, vulnerability scoring, and release governance platform. Built on a dual-engine architecture: a resilient serverless PostgreSQL backend with in-memory zero-latency caching and a keyboard-first terminal CLI (`mantis` / `bz`).

hub

Algorithmic CPM Graph

Topologically sorted DAG resolving release bottlenecks with cycle-rejection CTEs and auto-locking rules.

lock

90-Day Embargo & CVSS v4.0

Zero-leakage security boundaries with offline & live FIRST.org discrete MacroVector calculation.

psychology

Gemini 2.0 AI Synthesis

Instant thread summarization, root cause classification, and recommended action steps in under 2 seconds.

Mantis CLI Reference (`mantis` & `bz`)

Located in apps/cli, the CLI supports both mantis and bz binary aliases. It persists sessions to ~/.mantis-session.json and supports full UNIX stdin piping.

key1. Authentication & Switching Accounts

Switch to Alice (Senior Dev Lead Persona)

npm run mantis -- auth login --persona alice

Instantly authenticates as Alice to test dependency graphs, code reviews, and bug resolution.

Switch to Carol (Security Lead Persona)

npm run mantis -- auth login --persona carol

Switches to Carol to inspect confidential vulnerabilities and 90-day embargo countdowns.

Switch to Admin (System Administrator)

npm run mantis -- auth login --persona admin

Grants root workspace permissions, role escalation, and invite generation.

Switch to Bob (QA Automation)

npm run mantis -- auth login --persona bob

Switches to QA role to test defect verification, Kanban moves, and sprint burndowns.

Personal Account Login (Email & Password)

npm run mantis -- auth login --email "you@company.com" --password "your_password"

Logs into your private custom team workspace without using demo personas.

Inspect Active Session & Role Permissions

npm run mantis -- auth me

Prints active user display name, email, role (Admin/Member), groups, and team workspace name.

Override API Target (Live Production / Custom Port)

npm run mantis -- --api-url https://mantis-clonefest.vercel.app auth login --persona alice

Targets live Vercel production server or custom localhost port.

bug_report2. Bug Queue & State Transitions

List Active Bugs in Queue

npm run mantis -- bug list

Prints clean, uncluttered tabular view of ID, STATUS, PRIORITY, SEVERITY, and SECURITY embargoes.

Filter Bugs by Status and Priority

npm run mantis -- bug list --status CONFIRMED --priority P1

Filters list by specific state (UNCONFIRMED, CONFIRMED, IN_PROGRESS, RESOLVED, VERIFIED, CLOSED).

Stream Raw JSON Output

npm run mantis -- bug list --json

Outputs machine-readable JSON for scripting and CI/CD pipelines.

View Complete Bug Dossier

npm run mantis -- bug view 1

Displays summary, reporter, assignee, product, CVSS vector score, embargo date, and full description.

File a New Bug

npm run mantis -- bug create --summary "WebSocket timeout on network drop" --priority P1 --severity blocker

Creates a new defect in your active workspace team queue.

Transition Bug Status with Resolution Audit

npm run mantis -- bug status 1 RESOLVED --resolution FIXED

Moves bug lifecycle (Options: FIXED, INVALID, WONTFIX, DUPLICATE, WORKSFORME, INCOMPLETE).

chat3. Discussion Threads & Stdin Stream Piping

Read Comment Thread

npm run mantis -- comment list 1

Prints chronological comment thread with author badges and timestamps.

Post Comment via Argument

npm run mantis -- comment add 1 "Verified fix on Firefox 128.0 build."

Posts direct comment text to the bug discussion.

Pipe Markdown File or Log into Comment

cat crash_log.txt | npm run mantis -- comment add 1

Reads stdin stream directly into comment body (perfect for CI/CD stacktraces).

hub4. CPM Graphs, CVSS v4.0, AI & Standup Inbox

Render Visual ASCII CPM Graph

npm run mantis -- graph 1

Renders complete dependency tree highlighting upstream blockers and critical path bottleneck nodes.

Add Dependency Edge

npm run mantis -- dep add 1 2

Sets Bug #1 as blocking Bug #2 with cycle checks.

Offline CVSS v4.0 Scoring Calculator

npm run mantis -- cvss "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N"

Computes macrovector score (0.0–10.0) and severity rating (CRITICAL/HIGH/MEDIUM/LOW) offline.

Run Gemini AI Triage Assistant

npm run mantis -- triage 1

Runs Gemini 2.0 Flash to synthesize thread, identify root cause, and recommend next actions.

Check Velocity & MTTR Analytics

npm run mantis -- metrics velocity

Computes throughput (bugs/day), active issues, and Mean Time to Resolve (MTTR).

Milestone Release Readiness Score (0-100%)

npm run mantis -- readiness 128.0

Calculates release readiness gauge based on blocker resolution and verification rate.

Launch Daily Standup Triage Inbox

npm run mantis -- inbox

Shows actionable table of unconfirmed, blocker, and embargoed bugs requiring standup triage.

hubCritical Path Method (CPM & DAG) Algorithmic Depth

Mantis treats bug dependency hierarchies as a Directed Acyclic Graph (DAG). Powered by React Flow and Dagre, it continuously performs topological sorting (Kahn's algorithm) to detect critical path bottlenecks constraining target release dates.

▲ Upstream Blockers (Must be resolved first):

└── #100 [CONFIRMED] TLS certificate renegotiation bug CRITICAL PATH

● TARGET BUG: #101 [IN_PROGRESS] Core WebSocket Crash CRITICAL PATH

▼ Downstream Impact (Blocked by this bug):

└── #102 [CONFIRMED] Live notification sync fails

lock_clockAuto-Resolution Blocker Rule

A bug cannot transition to RESOLVED or CLOSED until all upstream blocker bugs have been resolved as FIXED.

all_inclusiveRecursive CTE Cycle Detection

Transactions execute recursive SQL CTEs prior to inserting dependency edges. Circular dependencies (`A → B → A`) immediately fail with HTTP 422 CYCLIC_DEPENDENCY_DETECTED.

lock90-Day Security Embargo & Interactive CVSS v4.0 Calculator

In accordance with Coordinated Vulnerability Disclosure (CVD), vulnerabilities marked as security bugs are sealed under a strict 90-day embargo. Only members in the security-team group can view or discuss the issue; all other requests receive HTTP 404 with zero metadata leakage.

FIRST.org CVSS v4.0 Score

9.0CRITICAL

CVSS:4.0/AV:N/AC:L/VC:H/VI:H/VA:H

Attack Vector (AV)

Attack Complexity (AC)

Vulnerability Conf (VC)

Algorithmic Health Engine

verifiedMilestone Release Readiness Score (0–100% Algorithmic Model)

Mantis computes an objective, deterministic release risk score for any milestone (e.g. Firefox 128.0). The engine evaluates base resolution progress against five discrete blocker risk factors:

Mathematical Scoring Model:

Readiness = max(0, min(100, round( S_base - 0.5 * ( 15 * N_CPM + 20 * N_CVSS_Crit + 10 * N_CVSS_High + 5 * N_Flags + 8 * N_P1 ) )))

• 15 pts / Blocker: Open Critical Path DAG bottlenecks

• 20 pts / Blocker: CVSS v4.0 Critical (Score ≥ 9.0)

• 10 pts / Blocker: CVSS v4.0 High (Score 7.0–8.9)

• 5 pts / Flag: Pending ? review or approval flags

• 8 pts / Bug: Open P1 / Blocker priority issues

READY_FOR_RELEASE

Score ≥ 85%

Zero critical path bottlenecks and minimal open risk.

NEEDS_ATTENTION

60% ≤ Score < 85%

Non-critical review flags or medium severity defects pending.

BLOCKED

Score < 60%

Target milestone is blocked by active CPM bottleneck chain or zero-day.

codeREST API Contract: GET /api/v1/analytics/readiness?milestone=128.0

Returns the aggregate score, status tier, exact penalty breakdown, list of unresolved bug IDs, and critical path IDs in real time.

Immutable Event Stream

manage_searchSystem-Wide Audit Explorer & Immutable Activity Stream (`/audit`)

Every mutation across the workspace is permanently recorded in an append-only PostgreSQL relational stream (`bugs_activity`). The Audit Explorer page provides server-side paginated queries with real-time field mutation filters.

filter_altSupported Field Filters

Status TransitionsResolutionsPrioritySeverityAssigneeCVSS ScoreEmbargoReview FlagsKeywordsCC List

securityRegulatory & Compliance Guarantee

Rows in `bugs_activity` are never updated or deleted. Full traceability ensures complete SOC2 and ISO 27001 audit compliance with actor identity, before/after diffs, and microsecond timestamps.

Query Workspace Audit Records

GET /api/v1/audit?limit=20&offset=0&field=bug_status

open_in_newOpen /audit

bookmarksSaved Views & Named Queries (JSONB Persistence)

Located directly above the main bug queue on the Dashboard, the SavedViewsBar allows engineers to save complex filter configurations into PostgreSQL JSONB with 1-click preset switching:

priority_highP1 Blockers

Active P1 critical blockers

lockSecurity Embargoed

Active 90-day embargoed zero-days

pending_actionsNeeds Triage

Unconfirmed queue awaiting triage

timelapseIn Progress

Active development sprints

task_altResolved Fixed

Verified and resolved fixes

add_circleCustom Queries

Save personal workspace named filters

REST API Endpoints:

• GET /api/v1/saved-views (Fetch system presets + user queries)

• POST /api/v1/saved-views (Body: { name: string, query_json: object })

• DELETE /api/v1/saved-views/:id (Delete user saved query)

labelBugzilla Keywords Classification Taxonomy

Mantis implements the official Bugzilla keyword taxonomy system for multi-dimensional ticket categorization across products:

#regressionDefect introduced by a recent commit

#crashMemory corruption or crash in renderer

#sec-auditSecurity audit finding

#perfPerformance degradation or jank

#topcrashHigh-frequency telemetry crash

#intermittentFlaky CI/CD test failure

#accessibilityScreen reader or a11y defect

Relational Architecture:

Keywords use a normalized relational structure (`keyword_defs` + `bug_keywords`). Tag additions and removals immediately write immutable audit trail records to `bugs_activity`.

notifications_activeCC / Watcher Subscriptions & Notification Pipeline

Developers, QA engineers, and security reviewers can watch any defect to receive real-time updates. The multi-cast dispatch pipeline automatically routes alerts when status, comments, or review flags change:

visibility1-Click Watch / Unwatch

Toggle watching on any defect detail page (`/bugs/:id`). CC subscriptions are stored in bug_cc with foreign key cascading.

notificationsHeader Notification Bell

Displays live unread count badges, instant popover preview with direct navigation links, and a 1-click "Mark all as read" action.

file_downloadStreamed RFC 4180 CSV Data Export

Mantis guarantees complete data portability with high-speed RFC 4180 compliant CSV streaming. Click the "Export CSV" button on the Dashboard to export any filtered queue:

GET /api/v1/bugs/export?status=all&priority=P1&severity=all&embargo=all

• RFC 4180 Compliant: Quotes, escapes delimiters, and formats timestamps automatically.

• 404 Zero-Leakage Security Masking: Non-security sessions automatically omit quarantined 90-day embargoed defects at the SQL level.

commitReal-Time GitHub SCM Webhook & Traceability

Mantis bridges git source code repositories directly to defect lifecycles with cryptographic webhook verification:

HMAC-SHA256 Security

Validates x-hub-signature-256 with crypto.timingSafeEqual.

Commit Parsing

Parses Fixes #1, Closes #1, Resolves #1, and Bug 1.

Auto-Resolution

Pushes to main automatically move bugs to RESOLVED (FIXED).

timer30-Second Live Evaluator Test

Push a commit to our pre-configured demo repository: https://github.com/OjasKugore/mantis-webhook-demo

git commit --allow-empty -m "Fix network timeout (Fixes #1)" && git push origin main

psychologyGemini 2.0 Flash AI Triage Engine

Mantis integrates Google DeepMind's Gemini 2.0 Flash to synthesize multi-page comment threads, diagnose stacktraces, and generate structured triage dossiers in under 2 seconds:

AI Synthesis Capabilities

✓Automatic Reproduction Extraction: Distills 50+ comments into 3 reproducible steps.
✓Root Cause Deduction: Analyzes linked PR diffs, stack traces, and subsystem ownership.
✓Confidence Scoring & Next Steps: Recommends priority (P1–P5) with rationale and immediate assigned action items.

view_kanbanKanban Board & FSM Rollback Integrity

The /kanban board provides agile workflow visualization across 6 status columns with strict finite state machine integrity:

UNCONFIRMED→CONFIRMED→IN_PROGRESS→RESOLVED→VERIFIED→CLOSED

Optimistic UI with Automatic FSM Rollback:

Dragging a card to an invalid column (e.g. UNCONFIRMED → CLOSED) is immediately rejected by the server state machine. The card automatically bounces back to its original column and shows an explanatory error toast.

query_statsSprint Burndown & Velocity (MTTR) Analytics

Located on the Dashboard under the Analytics tab, Mantis computes real-time sprint burndown trajectories and pure SQL MTTR metrics:

Throughput Velocity

3.4 bugs/day

Average sprint resolution pace

Mean Time to Resolve (MTTR)

18.5 Hours

From triage to verified fix

Milestone Readiness

92% Ready

Target: Firefox v128.0

search_checkStemmed Full-Text Search & Trigram Duplicate Prevention

Mantis provides two powerful textual engines to keep defect queues clean and instantly searchable:

travel_explorePostgreSQL FTS (`tsvector` + GIN)

Sub-20ms stemmed English search index. Searching "parse" matches "parsing", "parsed", and "parser" with highlighted mark tags.

content_copyProactive Duplicate Prevention (`pg_trgm`)

As an engineer types on /bugs/new, a debounced query checks trigram similarity (> 0.28). Candidate duplicate tickets are surfaced before form submission.

shield_personWorkspace Isolation & Role-Based Access Control (RBAC)

Mantis enforces strict per-team workspace isolation with granular group permissions:

Role / Group	Permissions	Confidential Embargo Access
Workspace Administrator	Full instance governance, user ranking escalation, invite tokens, seed reset.	Unrestricted
Security Lead (`security-team`)	CVSS v4.0 scoring, embargo management, CVE drafting.	Unrestricted
Senior Dev Lead (`dev-team`)	CPM graph manipulation, bug resolution, code reviews, PR flags.	Blocked during 90d embargo
QA Automation (`qa-team`)	Defect filing, milestone audits, verification sign-offs.	Blocked during 90d embargo

corporate_fareProduct Hierarchy, Team Invitations & Onboarding

Mantis provides complete self-service administration for engineering teams:

Product & Component Routing

Configure products and granular sub-components with default component assignees on /settings/products.

Time-Limited Token Invites

Generate secure invite links on /settings/team with pre-configured RBAC role binding.

Workspace Onboarding

Self-service workspace initialization with sensible defaults and triage queues on /onboarding.

flagCode Review Flags (`?`, `+`, `-`) & Patch Governance

Bugzilla-style flag gating is fully implemented on every bug report to separate review sign-offs from ticket status:

? (Requested)

Review requested from a specific teammate (e.g. review?alice).

+ (Granted)

Review approved. Unblocks landing the patch into release candidate branches.

- (Denied)

Changes requested or security exception denied.

alternate_emailGFM Markdown & Interactive @Mentions Collaboration

The comment editor provides an ultra-fast developer collaboration experience:

edit_noteDual-Tab Write / Preview Markdown

Supports GitHub-Flavored Markdown tables, checklists, callouts, and syntax-highlighted code fences with 1-click clipboard copy.

person_searchInteractive @Mentions Autocomplete

Typing @ opens an avatar typeahead popup. Mentioned engineers immediately receive in-app notification alerts.

Hidden Power-User Features & Capabilities

lock_reset1. One-Time Demo State Reset

Judges can test breaking things without fear. Trigger fetch('/api/v1/admin/reset', { method: 'POST' }) in console or click Reset Demo to re-seed all 24 initial bugs.

cookie2. Cold-Start Resilient JWT Cookie Fallback

Sessions seamlessly survive Vercel serverless cold starts using dual lookup: DB session table + HMAC-signed fallback token cookie (mantis_user_token).

share3. Shareable Open Invite Tokens

Admins can generate open invitation URLs that allow teammates to self-register into their workspace with pre-allotted RBAC roles in Incognito mode.

format_paint4. Dark / Light Mode Glassmorphism Theme

Curated HSL color design system with tailored sage green accents (#87a96b) and dark glassmorphic backdrops.

fact_checkAutomated Test Suite & Invariant Verification Matrix

Mantis contains 36 test suites with 141 named assertions, executing in ~4.2 seconds with a 100% green pass rate:

Verification Domain	Key Invariant Assertions Verified	Status
Topological Order & CPM	Kahn's algorithm identifies critical paths; recursive CTE rejects cyclic blocker edges with 422.	100% Passed
CVSS v4.0 Math Standard	Discrete MacroVectors match official FIRST.org benchmark vectors (9.3 CRITICAL, 8.7 HIGH, 1.8 LOW).	100% Passed
Finite State Machine	All 6 valid transitions succeed; illegal jumps and missing resolution codes abort with 422.	100% Passed
404 Zero-Leakage Secrecy	Non-security members requesting 90-day embargoed defects receive strict 404s with zero leakage.	100% Passed
Cryptographic Webhooks	Constant-time HMAC-SHA256 comparison; `Fixes #1` commit auto-resolves defect and appends audit entry.	100% Passed

keyboardKeyboard Shortcuts Cheatsheet

Open universal command palette & quick search⌘K / Ctrl+K

Open modal to file a new bug reportC

Navigate directly to DashboardG then D

Navigate directly to Kanban BoardG then K

Move selection up/down in bug listsJ / K

Show full keyboard shortcut cheatsheet modal?

Close open modals or clear search filterEsc

quizEvaluator FAQ & Troubleshooting

How do I test inviting another user in Incognito?expand_more

Go to Team Settings → Invite Member, generate an invite token link, copy it, and paste it into an Incognito window. Sign up or log in, and the user will automatically bind to your workspace with pre-allotted roles.

How do custom team workspaces isolate data from demo personas?expand_more

Non-demo users receive a private workspace scoped to their team_name. Custom accounts only see their team's bugs, members, and products, while evaluation personas remain preserved for hackathon judging.

Where is the 90-day security embargo countdown timer?expand_more

The active security embargo countdown timer is located directly at the top of each confidential security defect's detail page (e.g. /bugs/1 or /bugs/4), displaying the live countdown to its specific disclosure date.

How do I test GitHub SCM webhooks live right now?expand_more

Clone https://github.com/OjasKugore/mantis-webhook-demo and push a commit with message Fixes #1. Open Bug #1 on Mantis to see the commit in the SCM tab and the bug automatically moved to RESOLVED (FIXED).