Key Technical Concepts

This document maps the stable product concepts in Monkeys to their technical meaning across repositories. It complements the product development philosophy and the module architecture.

It is not an exhaustive API reference. Use it as a shared vocabulary for product design, implementation, refactoring, and agent-assisted development.

Concept Map

Data Concepts

Global Data

Product meaning: Global Data is the organization-level full historical fact layer. It keeps facts unified, governable, queryable, and reusable across product surfaces, workflows, and agents.

Technical meaning: Global Data should be treated as a system-level data layer, not a screen-specific model. Product interfaces may expose user-facing concepts such as data repositories, datasets, views, workspaces, tasks, or results while relying on Global Data underneath.

Used by:

• Data services and backend APIs
• Kernel data governance and configuration
• Studio data views and workflow applications
• Workflow execution and agent tools

Avoid:

• Treating Global Data as a UI label that must appear on every screen
• Storing duplicate business facts in isolated feature state
• Mixing Global Data with task context, runtime state, or generated artifacts before they are persisted as product data

Ontology

Product meaning: Ontology defines business semantics. It describes the kinds of business objects Monkeys understands and how their fields, relationships, and behaviors are organized.

Technical meaning: Ontology should be the stable abstraction for business objects. It is broader than a table, bucket, or storage namespace. New product behavior should prefer ontology-level modeling over hardcoded feature-specific schemas.

Used by:

• Data modeling and data governance
• Data import and normalization
• View and filter definition
• Workflow inputs and outputs
• Agent-readable data contracts

Avoid:

• Treating ontology as only a storage bucket alias
• Encoding business-specific ontology behavior directly in UI components
• Creating new data concepts when an existing ontology can express the same object

Entity And Record

Product meaning: An entity is a business object type defined by ontology. A record is a concrete instance of that entity.

Technical meaning: Entity and record contracts should be explicit enough for UI rendering, workflow execution, tool invocation, and agent operations. Records should carry enough identity, schema, and lineage information to be reused outside their original screen.

Used by:

• Data table and detail views
• Import and export flows
• Workflow payloads
• Agent read and write operations

Avoid:

• Treating records as anonymous JSON blobs when they represent business objects
• Losing stable identifiers across import, transformation, or generation
• Coupling record shape to one page layout

Field And Schema

Product meaning: Fields define the structure of business objects. Schema defines how fields combine into a coherent object model.

Technical meaning: Field and schema definitions should support validation, rendering, filtering, import, export, and agent use. Schema should be declarative when possible so product behavior can change through configuration.

Used by:

• Form generation
• Table and card rendering
• Data validation
• Query and filter construction
• Workflow input and output contracts

Avoid:

• Duplicating the same field definition across frontend, backend, and workflow code
• Hiding validation rules in page-level conditionals
• Using display labels as stable technical identifiers

Filter

Product meaning: A filter defines how a subset of data is selected.

Technical meaning: Filter is part of the access and query contract. It may combine search, field predicates, authorization-aware selection, and product-specific constraints. Filters should be reusable across views, workflows, and agent tools.

Used by:

• Data views
• Search and query APIs
• Workflow inputs
• Agent data access

Avoid:

• Reimplementing the same selection logic separately in each interface
• Treating filters as purely visual controls
• Allowing agent tools to bypass product-level filtering rules

View

Product meaning: A view is the user-facing or agent-facing way to inspect and act on data.

Technical meaning: A view is not the data itself. It is an access, layout, and interaction contract over data. Multiple views may present the same underlying facts for different workflows.

Used by:

• Studio workflow applications
• Kernel configuration surfaces
• Data repository and dataset experiences
• Agent-readable product surfaces

Avoid:

• Persisting business facts only inside view-specific state
• Treating a view as the owner of the data model
• Creating new backend concepts for every visual variation

Artifact

Product meaning: An artifact is a generated or uploaded output, such as a file, image, document, model result, workflow result, or structured record.

Technical meaning: Artifacts become product data when they are persisted, indexed, connected to ontology, and made available to views, workflows, or agents.

Used by:

• Workflow execution
• Agent output
• Studio applications
• Data import and generation flows
• Object storage and metadata services

Avoid:

• Leaving generated outputs untracked
• Losing the relationship between an artifact and the data, workflow, or tool that produced it
• Treating files as separate from the product data model when they carry business meaning

Workflow Concepts

Workflow

Product meaning: A workflow is an executable path through which data changes are produced, validated, and persisted.

Technical meaning: Workflow is more than automation UI. It is the execution contract that connects data, tools, tasks, state, artifacts, and user or agent actions.

Used by:

• Workflow applications
• Conductor-backed execution
• Long-running tasks
• Tool orchestration
• Agent-triggered operations

Avoid:

• Treating workflow as only a visual diagram
• Hiding data mutations inside task code without a clear contract
• Creating workflow outputs that cannot be persisted back into product data

Task

Product meaning: A task is an executable step inside a workflow.

Technical meaning: A task should have clear inputs, outputs, retries, state, errors, and ownership. It should be small enough to reason about and reliable enough to run in background execution.

Used by:

• Conductor workers
• Tool services
• Data processing flows
• Model and media generation flows

Avoid:

• Building tasks that depend on hidden page state
• Returning outputs without schema or artifact metadata
• Mixing unrelated responsibilities into one task

Trigger

Product meaning: A trigger starts a workflow or action.

Technical meaning: A trigger may come from user action, agent action, schedule, webhook, data change, or system event. Trigger contracts should define source, payload, permissions, and expected result.

Used by:

• Workflow applications
• Webhook services
• Agent runtime
• Background workers

Avoid:

• Starting workflows without an auditable source
• Treating triggers as untyped events
• Letting triggers bypass permissions or validation

State

Product meaning: State describes where a workflow, task, or product action is in its lifecycle.

Technical meaning: State should be explicit, durable when needed, and visible to the owning product surface. Long-running execution should expose enough state for recovery, debugging, and user feedback.

Used by:

• Workflow execution
• Runtime orchestration
• Studio progress UI
• Kernel configuration validation
• Backend job tracking

Avoid:

• Keeping critical state only in browser-only runtime state
• Collapsing all failures into a generic failed state
• Making state transitions impossible to audit

Agent And Tool Concepts

Agent

Product meaning: An agent is an action-taking actor that can read data, call tools, trigger workflows, generate artifacts, and move product state forward.

Technical meaning: Agent behavior should be constrained by product contracts: ontology, views, permissions, tool schemas, workflow contracts, and runtime policies.

Used by:

• Agent runtime services
• MCP access
• Tool invocation
• Workflow execution
• Product automation

Avoid:

• Letting agents bypass data contracts
• Giving agents page-only state when product data should be used
• Treating agent outputs as valid product data before validation and persistence

Tool

Product meaning: A tool is a reusable capability that can be called by workflows, agents, or product services.

Technical meaning: A tool should expose a clear contract: name, input schema, output schema, permissions, execution behavior, errors, and artifact handling.

Used by:

• Tool services
• Agent toolkits
• Workflow tasks
• Product integrations

Avoid:

• Adding tools without typed inputs and outputs
• Returning raw provider responses as stable product contracts
• Hiding side effects from the workflow or agent caller

Context

Product meaning: Context is the scoped information needed to complete a product action or agent task.

Technical meaning: Context should be derived from product data, user input, workflow state, or tool results. It should be scoped, explainable, and separate from the durable fact layer until it is intentionally persisted.

Used by:

• Agent execution
• Workflow task inputs
• Tool invocation
• Application state

Avoid:

• Treating temporary context as durable product facts
• Passing broad, unscoped context to tools or agents
• Hiding important context construction in prompt-only logic

Action Log

Product meaning: An action log records what happened, who or what initiated it, and what changed.

Technical meaning: Important user, workflow, and agent actions should produce enough trace information to support auditability, debugging, replay, and user trust.

Used by:

• Agent runtime
• Workflow execution
• Backend services
• Data governance

Avoid:

• Running important actions without traceability
• Logging only text summaries when structured fields are needed
• Losing links between actions, source data, tools, and resulting artifacts

Product Surface Concepts

Studio

Product meaning: Studio is the product application surface for creating, operating, and consuming data-driven workflows.

Technical meaning: Studio should present coherent applications and workflow experiences over shared product data. It should avoid owning hidden business models that cannot be reused by Kernel, Compute, workflows, or agents.

Kernel

Product meaning: Kernel is the configuration and governance surface for core system capabilities, data capabilities, and workflow capabilities.

Technical meaning: Kernel should expose stable configuration concepts and data-governance controls. It should make system behavior explicit instead of scattering configuration into application code.

Compute

Product meaning: Compute is the execution-oriented surface for runtime capabilities and automated work.

Technical meaning: Compute is connected to the shared data and workflow architecture, but it may own execution concepts that are more independent than ordinary product views. Shared data contracts should still be reused whenever Compute reads, writes, or triggers product data.

Code Map

Naming And Refactoring Rules

• Prefer Ontology for business semantic modeling in new concepts and public documentation.
• Treat legacy names such as bucket as compatibility aliases when encountered; do not expand them into new product concepts.
• Use Global Data only for the organization-level full historical fact layer.
• Use View for access and presentation over data, not for the data itself.
• Use Workflow for executable data-change paths, not only UI flow diagrams.
• Use Tool for typed capability contracts, not arbitrary helper code.
• Keep user-facing labels friendly, but keep code-level concepts stable.
• Put business variation into declarative data and configuration whenever possible.

Feature Design Checklist

Before adding a new feature, ask:

• Is this a new data concept, or a new view over existing data?
• Does an existing ontology already describe the object?
• What data does the feature create, consume, update, or persist?
• Should the behavior be configuration instead of code?
• Which product surface owns the primary experience?
• Does a workflow, tool, or agent need to read, write, or trigger it?
• What permissions, state transitions, and action logs are required?
• Where should generated artifacts be stored and connected back to product data?
• Can the result be reused outside the first screen where it appears?