# directus/directus architecture

> Architecture diagram of the GitHub repository directus/directus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/directus/directus
- Repository: https://github.com/directus/directus

## Overview

Directus is a collaborative backend that exposes existing SQL data through generated REST and GraphQL APIs, alongside a visual management Studio and AI/MCP access. The principal workflow is a user or agent accessing live data through an API or Studio, governed by policy-based permissions and backed by the configured database. The graph preserves documented extension and file-storage capabilities. README statements support the broad product relationships; sampled source confirms schema/database and extension-manager details, but many endpoint-to-service connections were not shown.

Main entry points: [`api/src/controllers/items.ts`](https://github.com/directus/directus/blob/main/api/src/controllers/items.ts) (REST API), [`api/src/controllers/graphql.ts`](https://github.com/directus/directus/blob/main/api/src/controllers/graphql.ts) (GraphQL API), [`api/src/ai/mcp/server.ts`](https://github.com/directus/directus/blob/main/api/src/ai/mcp/server.ts) (MCP server), [`api/src/permissions/lib/fetch-permissions.ts`](https://github.com/directus/directus/blob/main/api/src/permissions/lib/fetch-permissions.ts) (Policy access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API Runtime"]
  node_api["REST API<br/>[items.ts]"]
  node_graphql["GraphQL API<br/>[graphql.ts]"]
  node_permissions["Policy access"]
end

subgraph group_data["Data Platform"]
  node_schema["Schema discovery<br/>[get-schema.ts]"]
  node_database["Database runtime<br/>[index.ts]"]
  node_items["Item services<br/>[items.ts]"]
  node_collections["Collection services<br/>[collections.ts]"]
  node_fields["Field services<br/>[fields.ts]"]
  node_relations["Relation services<br/>[relations.ts]"]
  node_import["Data import<br/>[import.ts]"]
  node_storage["File storage<br/>[files.ts]"]
end

subgraph group_studio["Management Studio"]
  node_studio["Visual Studio<br/>[app.vue]"]
end

subgraph group_ai["AI Access"]
  node_chat["AI assistant<br/>[chat.post.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_tools["AI data tools<br/>[registry.ts]"]
end

subgraph group_ext["Extensibility"]
  node_extensions["Extension manager<br/>[manager.ts]"]
  node_extension_install["Extension installation<br/>[manager.ts]"]
end

node_user(("Builder or teammate"))
node_agent(("AI agent"))
node_sql[("SQL database")]

node_user -->|"manages data"| node_studio
node_studio -->|"accesses live data"| node_api
node_user -->|"requests data"| node_api
node_user -->|"queries data"| node_graphql
node_agent -->|"connects to"| node_mcp
node_mcp -->|"enforces policies"| node_permissions
node_api -->|"governed by"| node_permissions
node_graphql -->|"governed by"| node_permissions
node_schema -->|"inspects schema"| node_database
node_schema -->|"reads relations"| node_relations
node_database -->|"connects to"| node_sql
node_api -.->|"serves item access"| node_items
node_graphql -.->|"serves item access"| node_items
node_mcp -.->|"uses tools"| node_tools
node_tools -.->|"acts on data"| node_items
node_user -->|"imports data"| node_import
node_user -.->|"manages files"| node_storage
node_user -->|"extends platform"| node_extensions
node_extensions -->|"installs extensions"| node_extension_install

click node_api "https://github.com/directus/directus/blob/main/api/src/controllers/items.ts"
click node_graphql "https://github.com/directus/directus/blob/main/api/src/controllers/graphql.ts"
click node_permissions "https://github.com/directus/directus/blob/main/api/src/permissions/lib/fetch-permissions.ts"
click node_schema "https://github.com/directus/directus/blob/main/api/src/utils/get-schema.ts"
click node_database "https://github.com/directus/directus/blob/main/api/src/database/index.ts"
click node_items "https://github.com/directus/directus/blob/main/api/src/services/items.ts"
click node_collections "https://github.com/directus/directus/blob/main/api/src/services/collections.ts"
click node_fields "https://github.com/directus/directus/blob/main/api/src/services/fields.ts"
click node_relations "https://github.com/directus/directus/blob/main/api/src/services/relations.ts"
click node_import "https://github.com/directus/directus/blob/main/api/src/services/import/import.ts"
click node_storage "https://github.com/directus/directus/blob/main/api/src/services/files.ts"
click node_studio "https://github.com/directus/directus/blob/main/app/src/app.vue"
click node_chat "https://github.com/directus/directus/blob/main/api/src/ai/chat/controllers/chat.post.ts"
click node_mcp "https://github.com/directus/directus/blob/main/api/src/ai/mcp/server.ts"
click node_tools "https://github.com/directus/directus/blob/main/api/src/ai/tools/registry.ts"
click node_extensions "https://github.com/directus/directus/blob/main/api/src/extensions/manager.ts"
click node_extension_install "https://github.com/directus/directus/blob/main/api/src/extensions/lib/installation/manager.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_graphql,node_permissions toneBlue
class node_schema,node_database,node_items,node_collections,node_fields,node_relations,node_import,node_storage,node_sql toneAmber
class node_studio toneMint
class node_chat,node_mcp,node_tools toneRose
class node_extensions,node_extension_install,node_user,node_agent toneIndigo
```

## Components

### API Runtime

- [REST API](https://github.com/directus/directus/blob/main/api/src/controllers/items.ts): `api/src/controllers/items.ts`
- [GraphQL API](https://github.com/directus/directus/blob/main/api/src/controllers/graphql.ts): `api/src/controllers/graphql.ts`
- [Policy access](https://github.com/directus/directus/blob/main/api/src/permissions/lib/fetch-permissions.ts): `api/src/permissions/lib/fetch-permissions.ts`

### Data Platform

- [Schema discovery](https://github.com/directus/directus/blob/main/api/src/utils/get-schema.ts): `api/src/utils/get-schema.ts`
- [Database runtime](https://github.com/directus/directus/blob/main/api/src/database/index.ts): `api/src/database/index.ts`
- [Item services](https://github.com/directus/directus/blob/main/api/src/services/items.ts): `api/src/services/items.ts`
- [Collection services](https://github.com/directus/directus/blob/main/api/src/services/collections.ts): `api/src/services/collections.ts`
- [Field services](https://github.com/directus/directus/blob/main/api/src/services/fields.ts): `api/src/services/fields.ts`
- [Relation services](https://github.com/directus/directus/blob/main/api/src/services/relations.ts): `api/src/services/relations.ts`
- [Data import](https://github.com/directus/directus/blob/main/api/src/services/import/import.ts): `api/src/services/import/import.ts`
- [File storage](https://github.com/directus/directus/blob/main/api/src/services/files.ts): `api/src/services/files.ts`

### Management Studio

- [Visual Studio](https://github.com/directus/directus/blob/main/app/src/app.vue): `app/src/app.vue`

### AI Access

- [AI assistant](https://github.com/directus/directus/blob/main/api/src/ai/chat/controllers/chat.post.ts): `api/src/ai/chat/controllers/chat.post.ts`
- [MCP server](https://github.com/directus/directus/blob/main/api/src/ai/mcp/server.ts): `api/src/ai/mcp/server.ts`
- [AI data tools](https://github.com/directus/directus/blob/main/api/src/ai/tools/registry.ts): `api/src/ai/tools/registry.ts`

### Extensibility

- [Extension manager](https://github.com/directus/directus/blob/main/api/src/extensions/manager.ts): `api/src/extensions/manager.ts`
- [Extension installation](https://github.com/directus/directus/blob/main/api/src/extensions/lib/installation/manager.ts): `api/src/extensions/lib/installation/manager.ts`

### Other components

- **Builder or teammate**
- **AI agent**
- **SQL database**

## Connections

- Builder or teammate → Visual Studio: manages data
- Visual Studio → REST API: accesses live data
- Builder or teammate → REST API: requests data
- Builder or teammate → GraphQL API: queries data
- AI agent → MCP server: connects to
- MCP server → Policy access: enforces policies
- REST API → Policy access: governed by
- GraphQL API → Policy access: governed by
- Schema discovery → Database runtime: inspects schema (evidence: `api/src/utils/get-schema.ts`)
- Schema discovery → Relation services: reads relations (evidence: `api/src/utils/get-schema.ts`)
- Database runtime → SQL database: connects to
- REST API → Item services: serves item access
- GraphQL API → Item services: serves item access
- MCP server → AI data tools: uses tools
- AI data tools → Item services: acts on data
- Builder or teammate → Data import: imports data
- Builder or teammate → File storage: manages files
- Builder or teammate → Extension manager: extends platform
- Extension manager → Extension installation: installs extensions (evidence: `api/src/extensions/manager.ts`)
