Entities and states

This page maps the product concepts to the actual source entities in okto-pulse-core/src/okto_pulse/core/models/db.py and their API schemas in models/schemas.py. Use it when you need to know what Pulse stores, which lifecycle values are valid, and where each object is reachable.

Core delivery entities

Entity	Source model	Primary routes	MCP surface	Purpose
Agent	`Agent`	`/api/v1/agents`	Board management tools	Actor that owns an API key, permissions, and board access.
Agent board grant	`AgentBoard`	`/api/v1/agents/{agent_id}/boards/{board_id}`	Agent access tools	Board-scoped access row with optional permission overrides.
Permission preset	`PermissionPreset`	`/api/v1/presets`	Permission and agent tools	Named permission set that can be attached to agents.
Board	`Board`	`/api/v1/boards`	`okto_pulse_get_board`, board CRUD tools	Workspace container for the SDLC graph.
Ideation	`Ideation`	`/api/v1/boards/{board_id}/ideations`, `/api/v1/ideations/{ideation_id}`	Ideation tools	Initial problem statement and ambiguity-killer workflow.
Refinement	`Refinement`	`/api/v1/ideations/{ideation_id}/refinements`, `/api/v1/refinements/{refinement_id}`	Refinement tools	Evidence-gathering phase between ideation and spec.
Spec	`Spec`	`/api/v1/boards/{board_id}/specs`, `/api/v1/specs/{spec_id}`	Spec tools	Delivery contract with requirements, criteria, scenarios, decisions, rules, contracts, and TRs.
Sprint	`Sprint`	`/api/v1/boards/{board_id}/sprints`, `/api/v1/sprints/{sprint_id}`	Sprint tools	Scope slice that groups cards and closes through sprint evaluation.
Card	`Card`	`/api/v1/boards/{board_id}/cards`, `/api/v1/cards/{card_id}`	Card and task tools	Execution unit: normal work, test task, or bug task.
Card dependency	`CardDependency`	`/api/v1/cards/{card_id}/dependencies`	Dependency tools	`depends_on` relationship between two cards.

Evidence and collaboration entities

Entity	Source model	Primary routes	Purpose
Q&A item	`QAItem`, `IdeationQAItem`, `RefinementQAItem`, `SpecQAItem`, `SprintQAItem`	`/api/v1/qa/*`, `/{entity}/{id}/qa`	Structured questions and answers on cards and SDLC artifacts.
Comment	`Comment`	`/api/v1/comments/*`	Text comments and single/multi-choice comment boards on cards.
Attachment	`Attachment`	`/api/v1/attachments/{board_id}/{card_id}`	Uploaded files attached to cards.
Guideline	`Guideline`, `BoardGuideline`	`/api/v1/guidelines`, `/api/v1/boards/{board_id}/guidelines`	Global or board-specific rules agents must read before work.
Activity log	`ActivityLog`	`/api/v1/cards/{card_id}/activity`	Audit trail for card-visible changes.
Seen marker	`AgentSeenItem`	`/api/v1/cards/{card_id}/seen`	Per-agent unread/seen state for mentions and changes.
Validation	JSON records on `Card`, `Spec`, and `Sprint` plus validation response schemas	Card/spec/sprint validation routes	Independent review and lifecycle gate evidence.

Spec sub-objects

These are stored inside a spec payload, exposed through spec routes and MCP spec tools, and copied into card context when work starts.

Object	Source schema/model	Purpose
Business rule	`BusinessRule`	Rule linked to one or more functional requirements and implementation cards.
API contract	`ApiContract`	Endpoint or integration contract with method, path, payload shape, and linked cards.
Technical requirement	TR object in `Spec`	Non-functional or implementation-level requirement linked to tasks.
Acceptance criterion	AC list in `Spec`	User-visible condition that must be covered by scenarios and tasks.
Test scenario	`TestScenario` payload	Testable scenario; must be linked to test cards before validation.
Decision	Decision payload in `Spec`	Explicit architecture/product choice; can be active, superseded, or revoked.
Screen mockup	`ScreenMockup`, `MockupAnnotation`	HTML mockup and annotations attached to ideations, refinements, specs, or cards.
Architecture design	`ArchitectureDesign`, `ArchitectureDesignVersion`, `ArchitectureDiagram`	Structured architecture payloads, diagrams, versions, and diffs.

Knowledge entities

Entity	Source model	Primary routes/tools	Purpose
Ideation knowledge	`IdeationKnowledgeBase`	`/api/v1/ideations/{id}/knowledge`, MCP knowledge tools	Evidence attached before refinement/spec derivation.
Refinement knowledge	`RefinementKnowledgeBase`	`/api/v1/refinements/{id}/knowledge`, MCP knowledge tools	Evidence gathered during refinement.
Spec knowledge	`SpecKnowledgeBase`	`/api/v1/specs/{id}/knowledge`, MCP knowledge tools	Source material attached to the delivery contract.
Card knowledge	JSON records on `Card.knowledge_bases`	`/api/v1/cards/{id}/knowledge`, MCP knowledge tools	Context copied or written directly onto a task.
Consolidation queue	`ConsolidationQueue`	`/api/v1/kg/boards/{board_id}/pending`	SQLite work queue that drains artifacts into the graph.
Consolidation dead letter	`ConsolidationDeadLetter`	`/api/v1/kg/queue/dead-letter`, KG DLQ MCP tools	Failed KG consolidation work that exhausted retries.
Consolidation audit	`ConsolidationAudit`	`/api/v1/kg/boards/{board_id}/audit`	System-of-record for committed KG sessions.
KG tick run	`KGTickRun`	`/api/v1/kg/tick/run-now`, KG health	Relevance decay tick execution record.
Domain event	`DomainEventRow`, `DomainEventHandlerExecution`	Event dispatcher internals	Durable event and handler execution tracking.

Discovery and analytics entities

Entity	Source model/schema	Route family	Purpose
Discovery intent	`DiscoveryIntent`	`/api/v1/discovery/intents`	Saved operator intent that maps to a tool-backed discovery action.
Saved search	`DiscoverySavedSearch`	`/api/v1/discovery/boards/{board_id}/saved-searches`	Reusable board search.
Search history	`DiscoverySearchHistory`	`/api/v1/discovery/boards/{board_id}/search-history`	History of executed discovery searches.
Analytics entity row	Analytics response schemas	`/api/v1/boards/{board_id}/analytics/entities`	Spec, ideation, card, sprint, agent, and board metrics for dashboards and exports.

Status enums

Enum	Values
`IdeationStatus`	`draft`, `review`, `approved`, `evaluating`, `done`, `cancelled`
`IdeationComplexity`	`small`, `medium`, `large`
`RefinementStatus`	`draft`, `review`, `approved`, `done`, `cancelled`
`SpecStatus`	`draft`, `review`, `approved`, `validated`, `in_progress`, `done`, `cancelled`
`SprintStatus`	`draft`, `active`, `review`, `closed`, `cancelled`
`CardStatus`	`not_started`, `started`, `in_progress`, `validation`, `on_hold`, `done`, `cancelled`
`CardPriority`	`critical`, `very_high`, `high`, `medium`, `low`, `none`
`CardType`	`normal`, `bug`, `test`
`BugSeverity`	`critical`, `major`, `minor`
`CommentType`	`text`, `choice`, `multi_choice`

Lifecycle relationships

Parent	Children
Board	Ideations, agents, guidelines, KG graph, queue, and audit rows
Ideation	Refinements and specs
Refinement	Specs, knowledge, mockups, architecture, Q&A, snapshots, and history
Spec	Sprints, cards, business rules, API contracts, test scenarios, decisions, knowledge, mockups, architecture, Q&A, validations, and history
Sprint	Assigned cards, evaluations, Q&A, and history
Card	Dependencies, knowledge, mockups, architecture, Q&A, comments, attachments, conclusions, validations, and activity

Important invariants:

Cards should link to a spec; bug and test cards have additional scenario-link rules.
A sprint closes only after sprint evaluation and test evidence checks pass.
A normal card reaches done through the task validation gate.
Spec approved to validated requires coverage validation; validated to in_progress requires spec evaluation.
Deleting ideations or refinements can remove a full subtree; use archive/restore for reversible hiding.

See SDLC flow, Validation gates, and REST route catalog for the operational surfaces.

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Entities and states

Entities and states

Core delivery entities

Evidence and collaboration entities

Spec sub-objects

Knowledge entities

Discovery and analytics entities

Status enums

Lifecycle relationships

​Entities and states

​Core delivery entities

​Evidence and collaboration entities

​Spec sub-objects

​Knowledge entities

​Discovery and analytics entities

​Status enums

​Lifecycle relationships

Entities and states

Core delivery entities

Evidence and collaboration entities

Spec sub-objects

Knowledge entities

Discovery and analytics entities

Status enums

Lifecycle relationships