> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts at a glance

> A skimmable map of the ideas behind ModuleX: workflows and runs, nodes, the AI Composer, the Assistant, knowledge and RAG, credits, and organizations.

export const MediaEmbed = ({id, type = 'screenshot', caption = '', ext, ratio = '16 / 9'}) => {
  const isVideo = type === 'video' || type === 'app_video';
  const resolvedExt = ext || (isVideo ? 'mp4' : type === 'screenshot' ? 'webp' : 'svg');
  const src = 'https://media.modulex.dev/' + id + '.' + resolvedExt;
  const [status, setStatus] = useState('loading');
  const [isDev, setIsDev] = useState(false);
  const [inView, setInView] = useState(false);
  const boxRef = useRef(null);
  useEffect(() => {
    if (typeof window === 'undefined') return;
    const h = window.location.hostname;
    setIsDev(h === 'localhost' || h === '127.0.0.1' || h.endsWith('.mintlify.app'));
  }, []);
  useEffect(() => {
    if (inView) return;
    if (typeof IntersectionObserver === 'undefined') {
      setInView(true);
      return;
    }
    const el = boxRef.current;
    if (!el) return;
    const io = new IntersectionObserver(entries => {
      if (entries.some(e => e.isIntersecting)) {
        setInView(true);
        io.disconnect();
      }
    }, {
      rootMargin: '300px'
    });
    io.observe(el);
    return () => io.disconnect();
  }, [inView]);
  if (status === 'missing') {
    if (!isDev) return null;
    return <div style={{
      display: 'flex',
      flexDirection: 'column',
      justifyContent: 'center',
      gap: '0.4rem',
      padding: '1rem 1.25rem',
      margin: '1.25rem 0',
      width: '100%',
      aspectRatio: ratio,
      boxSizing: 'border-box',
      border: '1px dashed rgba(128,128,128,0.45)',
      borderRadius: '0.75rem',
      background: 'rgba(128,128,128,0.06)',
      color: 'currentColor',
      fontSize: '0.85rem',
      lineHeight: 1.45
    }}>
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '0.5rem',
      opacity: 0.75
    }}>
          <span aria-hidden="true">🎬</span>
          <code style={{
      fontSize: '0.75rem'
    }}>{id}</code>
          <span style={{
      fontSize: '0.65rem',
      textTransform: 'uppercase',
      letterSpacing: '0.04em',
      padding: '0.1rem 0.4rem',
      borderRadius: '0.4rem',
      background: 'rgba(128,128,128,0.18)'
    }}>
            {type}
          </span>
        </div>
        <div style={{
      opacity: 0.9
    }}>{caption || 'Media not uploaded yet.'}</div>
        <div style={{
      fontSize: '0.7rem',
      opacity: 0.5
    }}>
          Upload to R2 as <code>{id}.{resolvedExt}</code> — preview only, hidden in production.
        </div>
      </div>;
  }
  const mediaStyle = {
    display: status === 'loaded' ? 'block' : 'none',
    width: '100%',
    height: 'auto',
    borderRadius: '0.75rem'
  };
  const media = isVideo ? <video src={inView ? src : undefined} autoPlay loop muted playsInline preload="metadata" onLoadedData={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} /> : <img src={inView ? src : undefined} alt={caption} onLoad={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} />;
  return <figure style={{
    margin: '1.25rem 0'
  }}>
      <div ref={boxRef} style={status === 'loaded' ? {
    width: '100%'
  } : {
    width: '100%',
    aspectRatio: ratio,
    borderRadius: '0.75rem',
    background: 'rgba(128,128,128,0.06)'
  }}>
        {media}
      </div>
      {status === 'loaded' && caption ? <figcaption style={{
    marginTop: '0.5rem',
    textAlign: 'center',
    fontSize: '0.85rem',
    opacity: 0.7
  }}>
          {caption}
        </figcaption> : null}
    </figure>;
};

This page is a map, not a manual. It defines the words you will meet everywhere else in the docs and points you to the page that covers each one in depth. Read it top to bottom once, then come back whenever a term is unfamiliar.

If you only remember one sentence: **you build a workflow, you run it, and ModuleX meters managed usage in credits — all inside an organization.**

<MediaEmbed id="MX-MEDIA-1020" type="image" caption={"A single concept map that shows how the core ideas connect."} />

## The building blocks

Start here. These four terms describe what you make and what happens when you press run.

<CardGroup cols={2}>
  <Card title="Workflow" icon="diagram-project" href="/concepts/workflows-and-runs">
    A **workflow** is an editable graph that connects tools, data, and agents into a repeatable process. You build it on the visual canvas or generate it from a prompt with the AI Composer.
  </Card>

  <Card title="Run" icon="play" href="/concepts/workflows-and-runs">
    A **run** is one execution of a workflow. Each run streams its progress live and ends in a final state you can inspect. You can run from chat, the API, or an SDK.
  </Card>

  <Card title="Node" icon="square-dashed" href="/workflow-builder/nodes/overview">
    A **node** is one step in a workflow. Every node writes its result back into the run so later steps can use it. ModuleX has nine node types.
  </Card>

  <Card title="Reference" icon="link" href="/concepts/workflow-engine">
    A **reference** — written `{{node_id.field}}` — pulls a value from an earlier node into a later one. References are how data flows between steps.
  </Card>
</CardGroup>

### The nine node types

A workflow is assembled from a fixed set of nine **node types**. You do not need to memorize them now — each links to its own reference page.

<CardGroup cols={3}>
  <Card title="LLM" icon="message-bot" href="/workflow-builder/nodes/llm">
    Call a language model with a prompt and optional structured output.
  </Card>

  <Card title="Agent" icon="robot" href="/workflow-builder/nodes/agent">
    Run an autonomous step that can call tools and loop until it is done.
  </Card>

  <Card title="Knowledge" icon="book-open" href="/workflow-builder/nodes/knowledge">
    Retrieve relevant context from a knowledge base inside a run.
  </Card>

  <Card title="Tool" icon="plug" href="/workflow-builder/nodes/tool">
    Call one action from a connected integration.
  </Card>

  <Card title="Function" icon="code" href="/workflow-builder/nodes/function">
    Run a built-in function such as an HTTP request or a webhook.
  </Card>

  <Card title="Conditional" icon="code-branch" href="/workflow-builder/nodes/conditional">
    Branch on an expression or an LLM decision, or loop over data.
  </Card>

  <Card title="Interrupt" icon="hand" href="/workflow-builder/nodes/interrupt">
    Pause the run to ask a person a question, then resume with their answer.
  </Card>

  <Card title="Transformer" icon="shuffle" href="/workflow-builder/nodes/transformer">
    Reshape, map, and combine data between steps.
  </Card>

  <Card title="Guardrails" icon="shield-check" href="/workflow-builder/nodes/guardrails">
    Validate content with schema, regex, or PII checks before it moves on.
  </Card>
</CardGroup>

## The two AI helpers

ModuleX has two assistants, and they are easy to mix up. The short version: **the AI Composer builds workflows; the Assistant gets work done without one.**

<CardGroup cols={2}>
  <Card title="AI Composer" icon="wand-magic-sparkles" href="/concepts/ai-composer">
    The text-to-workflow agent. Describe what you want in plain English and the **AI Composer** turns it into a complete, editable workflow graph — then keeps editing the canvas as you chat with it.
  </Card>

  <Card title="Assistant" icon="comments" href="/concepts/assistant">
    A workflow-independent agentic chat. The **Assistant** searches your connected tools, decides the next step, calls tools, drafts outputs, and pauses for your approval before sensitive actions — no workflow required.
  </Card>
</CardGroup>

<Accordion title="When do I use which one?">
  Use the **AI Composer** when you want a reusable process you can run again and again — for example, "every time a form is submitted, summarize it and post to Slack." The Composer produces a workflow you own and can edit on the canvas.

  Use the **Assistant** for one-off or open-ended tasks where you do not want to build anything first — for example, "find the three most recent issues in this repo and draft a reply." The Assistant acts directly using your connected tools.

  Both can stop and ask you for input or approval mid-task. That pause-and-resume behavior is called **human-in-the-loop**.
</Accordion>

## Knowledge and RAG

**Knowledge** is your own content — documents, files, and data — made searchable so a workflow or the Assistant can pull in relevant context automatically. The retrieval technique behind this is **RAG** (retrieval-augmented generation).

<CardGroup cols={2}>
  <Card title="Knowledge base" icon="database" href="/concepts/knowledge-rag">
    A **knowledge base** is the unit RAG searches over. You add documents to it; ModuleX splits them into chunks and indexes them for retrieval.
  </Card>

  <Card title="Managed vs your own store" icon="server" href="/platform/knowledge/external-providers">
    Use the ModuleX-managed store (`modulexdb`), or bring your own vector store such as Qdrant, Pinecone, MongoDB Atlas, or Weaviate. Managed retrieval and ingest are billed in credits; bring-your-own stores are not.
  </Card>
</CardGroup>

## Connecting the outside world

A **workflow** or the **Assistant** is only as useful as what it can reach. That is what integrations are for.

<CardGroup cols={2}>
  <Card title="Integration" icon="puzzle-piece" href="/integrations/overview">
    An **integration** is a connector to an external service — Slack, GitHub, Google, and more. ModuleX ships **175** integrations.
  </Card>

  <Card title="Tool" icon="screwdriver-wrench" href="/integrations/overview">
    A **tool** is one callable action an integration exposes (for example, "create an issue"). A single integration usually exposes many tools.
  </Card>

  <Card title="Credential" icon="key" href="/concepts/credentials-oauth">
    A **credential** is the stored, encrypted connection that lets ModuleX act on your behalf in an external service — for example an OAuth2 connection or an API key.
  </Card>

  <Card title="BYOK" icon="lock-open" href="/integrations/llm-providers/overview">
    **BYOK** (bring your own key) lets you connect your own model or service accounts. Usage you bring is billed by that provider, not metered as ModuleX credits.
  </Card>
</CardGroup>

## How usage is paid for

Managed usage runs on **credits**. Bring-your-own-key usage does not consume credits — it is billed directly by your provider.

<CardGroup cols={2}>
  <Card title="Credit" icon="coins" href="/billing/credits">
    A **credit** is the unit that meters ModuleX-managed usage. \*\*100 credits equal $1.00** (one credit is $0.01). Each run, managed model call, and managed retrieval consumes credits.
  </Card>

  <Card title="Plan" icon="layer-group" href="/billing/plans">
    Your **plan** sets your monthly credit allowance and limits. The plans are **Free**, **Pro**, **Max**, and **Enterprise**.
  </Card>

  <Card title="Wallet" icon="wallet" href="/billing/wallet">
    The prepaid **wallet** covers usage beyond your plan's allowance once you turn on extra usage. Top it up manually or automatically.
  </Card>

  <Card title="The usage gate" icon="gauge" href="/billing/usage-gating">
    Before a run, Composer turn, Assistant turn, or managed knowledge call starts, ModuleX checks that you have credit and capacity. If you do not, the request is declined with a clear billing error instead of running and failing.
  </Card>
</CardGroup>

<Note>
  The usage gate is live on the run, AI Composer, Assistant, and managed-knowledge surfaces. When it declines a request you get a `402`, `403`, or `429` response carrying a structured reason. Plain create-read-update-delete and organization-settings calls are not gated this way. See [Usage gating & limits](/billing/usage-gating) and [Errors & status codes](/api-reference/errors) for the exact shapes.
</Note>

## Where everything lives: organizations

Everything in ModuleX belongs to an **organization**. It is the tenant and billing boundary — your workflows, credentials, knowledge bases, plan, wallet, and credits are all scoped to one organization.

<CardGroup cols={2}>
  <Card title="Organization" icon="building" href="/concepts/organizations-roles">
    An **organization** is the shared workspace and billing unit. People you invite become members of it, and every run is metered against its plan and credits.
  </Card>

  <Card title="Roles" icon="user-shield" href="/security/roles-permissions">
    Each member has a **role**. The live roles are **owner** and **admin**. Actions such as using the AI Composer, the Assistant, and schedules require owner or admin.
  </Card>
</CardGroup>

<Note>
  Earlier ModuleX had a separate "member" role. It has been **retired** — the current roles are **owner** and **admin** only. If you see "member" referenced in older material, treat it as out of date.
</Note>

## Working together in real time

ModuleX is multi-user. Two things stream live, and they travel over different channels — worth knowing because the rest of the docs keep them separate.

<CardGroup cols={2}>
  <Card title="Run streaming" icon="wave-pulse" href="/concepts/realtime-model">
    While a run executes, its progress streams to you event by event, so you can watch each node complete in real time.
  </Card>

  <Card title="Canvas collaboration" icon="users" href="/platform/collaboration/canvas">
    Several people can edit the same workflow canvas at once, with live cursors, presence, and locks so edits do not collide.
  </Card>
</CardGroup>

## Keep going

<CardGroup cols={3}>
  <Card title="How ModuleX works" icon="route" href="/concepts/overview">
    See these concepts as one end-to-end flow, from a prompt to a running, observable workflow.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Create an organization, get an API key, and make your first authenticated call.
  </Card>

  <Card title="Glossary" icon="spell-check" href="/reference/glossary">
    The full canonical term list, including the exact spellings the docs standardize on.
  </Card>
</CardGroup>