> ## Documentation Index > Fetch the complete documentation index at: https://docs.oktolabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Entities and states > Reference map of Pulse domain entities, persisted records, status enums, and where each surface is exposed. # 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](/concepts/sdlc-flow), [Validation gates](/reference/mcp/validation), and [REST route catalog](/reference/rest-api-catalog) for the operational surfaces.