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

# Architecture

> How Dino's pipeline processes your API from discovery to report.

## The pipeline

Dino processes your API in four stages. Each stage is isolated, testable, and deterministic.

```mermaid theme={null}
graph LR
    A[Discovery] --> B[Module execution]
    B --> C[Catalog]
    C --> D[Report]
```

<Steps>
  <Step title="Discovery">
    Dino discovers your surface in one of two ways, driven by the tenant `apis[].type`:

    * **GraphQL**: introspection against your endpoint; captures types, fields, arguments, directives; enumerates queries and mutations
    * **REST**: OpenAPI **3.0 / 3.1** parsing from `specPath` (URL or file); enumerates paths, methods, parameters, and response schemas

    In both cases, the result is a normalised operation list and a snapshot suitable for diffing.
  </Step>

  <Step title="Module execution">
    Shipped quality modules run against every discovered operation. Each module tests one dimension:  input handling, response correctness, access control, rate limiting, error formatting, deprecation tracking, and (for REST) transport/schema/header hardening via `rest-fuzzer`.

    No module depends on another module's output. They run concurrently where safe and produce independent findings. A failure in one module never blocks or corrupts another.

    See [The 12 Agents](/how-it-works/agents) for module-by-module detail.
  </Step>

  <Step title="Catalog">
    Findings from all modules are merged into a unified operational catalogue. Each operation gets:

    * A health score (0-100) based on findings across all dimensions
    * Metadata: argument types, return types, deprecation status (GraphQL); parameters and response codes (REST)
    * AI-generated descriptions (additive: the catalogue exists with or without them)
  </Step>

  <Step title="Report">
    The catalogue is rendered into JSON or Markdown. Every report includes the schema snapshot it was generated from, so you can diff between runs and see exactly what changed.
  </Step>
</Steps>

## Package architecture

Dino is a monorepo with strict dependency direction. Dependencies flow one way only.

```mermaid theme={null}
graph TD
    CLI["@dino/cli"] --> AGENTS["@dino/agents"]
    AGENTS --> PLUGINS["@dino/plugins"]
    PLUGINS --> CORE["@dino/core"]
    CLI --> REASONING["@dino/reasoning"]
    CLI --> ANALYTICS["@dino/analytics"]
```

<CardGroup cols={2}>
  <Card title="@dino/core" icon="cube">
    Schema types, shared interfaces, deterministic primitives (Clock, Timer, RandomSource). Zero dependencies on anything above it.
  </Card>

  <Card title="@dino/plugins" icon="puzzle-piece">
    Discovery plugins — **GraphQL introspection** and **OpenAPI** loading. Depends only on core types.
  </Card>

  <Card title="@dino/agents" icon="robot">
    Quality modules — fuzzing, validation, RBAC matrix, rate limits, errors, deprecation, REST fuzzing. Orchestrated by the pipeline; no imports from the CLI.
  </Card>

  <Card title="@dino/cli" icon="terminal">
    The `dino` command. Config loading, pipeline wiring, output rendering. Top of the dependency chain.
  </Card>

  <Card title="@dino/reasoning" icon="brain">
    AI-assisted descriptions and explanations. Additive — everything works without it.
  </Card>

  <Card title="@dino/analytics" icon="chart-line">
    Event tracking, historical comparisons, and regression detection across scan runs.
  </Card>
</CardGroup>

<Info>
  The strict dependency direction (`cli → agents → plugins → core`) is enforced at build time. A plugin cannot import from an agent. An agent cannot import from the CLI.
</Info>

## What this means for you

<AccordionGroup>
  <Accordion title="Reproducible results">
    The pipeline is deterministic. Same API state in, same findings out. See [Deterministic Engine](/how-it-works/deterministic-engine).
  </Accordion>

  <Accordion title="Fast feedback">
    Modules run in parallel where safe. A multi-module scan is a single pass with concurrent workers, not a long, serial waterfall.
  </Accordion>

  <Accordion title="CI-native">
    JSON output, exit codes, and schema snapshots for diffing. Built for pipelines, not dashboards.
  </Accordion>

  <Accordion title="No lock-in">
    Every output is a file you own. JSON reports, Markdown docs, schema snapshots, stored in your repo. If you stop using Dino, your data stays.
  </Accordion>
</AccordionGroup>