# falkordb/falkordb-browser architecture

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

- Interactive diagram: https://gitdiagram.com/falkordb/falkordb-browser
- Repository: https://github.com/falkordb/falkordb-browser

## Overview

FalkorDB Browser is a web UI for connecting to FalkorDB, querying and exploring graphs, and administering graph data and server access. The main workflow is: a user connects to a database, writes Cypher, submits it through the query API, and explores results in the graph canvas or table. Separate branches cover graph management and imports, optional AI assistance, and administration. The README documents these product capabilities; source excerpts are partial, so the graph avoids asserting unshown internal routing details.

Main entry points: [`app/api/run-query.ts`](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/run-query.ts) (Query execution), [`app/components/EditorComponent.tsx`](https://github.com/falkordb/falkordb-browser/blob/staging/app/components/EditorComponent.tsx) (Cypher editor), [`app/api/graph/[graph]/load-csv/route.ts`](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/load-csv/route.ts) (CSV import API), [`app/settings/page.tsx`](https://github.com/falkordb/falkordb-browser/blob/staging/app/settings/page.tsx) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connect["Connection and access"]
  node_connection_ui["Connections"]
  node_auth["Session and auth<br/>[options.ts]"]
  node_connection_api["Connection API<br/>[route.ts]"]
end

subgraph group_query["Query and exploration"]
  node_editor["Cypher editor"]
  node_query_api["Query execution<br/>[run-query.ts]"]
  node_canvas["Graph canvas<br/>[GraphView.tsx]"]
  node_table["Table view<br/>[TableView.tsx]"]
  node_history["Query history"]
  node_plans["Plans and metadata<br/>[MetadataView.tsx]"]
end

subgraph group_manage["Graph management"]
  node_graph_api["Graph operations<br/>[route.ts]"]
  node_graph_ui["Graph management UI<br/>[CreateGraph.tsx]"]
  node_element_api["Element editing API<br/>[route.ts]"]
  node_csv_ui["CSV import UI<br/>[UploadGraph.tsx]"]
  node_csv_api["CSV import API<br/>[route.ts]"]
  node_csv_storage["Temporary CSV storage<br/>[csv-storage.ts]"]
end

subgraph group_assist["AI assistance"]
  node_chat_ui["AI chat and tools<br/>[Chat.tsx]"]
  node_chat_api["AI chat API<br/>[route.tsx]"]
  node_models_api["AI model discovery<br/>[route.ts]"]
end

subgraph group_admin["Administration"]
  node_settings["Settings<br/>[page.tsx]"]
  node_users_api["Users and roles API<br/>[route.ts]"]
  node_tokens_ui["Access tokens"]
  node_udf_ui["UDF management<br/>[page.tsx]"]
  node_udf_api["UDF API<br/>[route.ts]"]
end

node_user(("User"))
node_database[("FalkorDB")]

node_user -->|"connects to"| node_connection_ui
node_connection_ui -->|"manages connections"| node_connection_api
node_connection_api -->|"uses session"| node_auth
node_user -->|"writes Cypher"| node_editor
node_editor -->|"submits query"| node_query_api
node_query_api -->|"runs Cypher"| node_database
node_query_api -->|"returns results"| node_canvas
node_query_api -->|"returns results"| node_table
node_editor -->|"reviews history"| node_history
node_query_api -->|"provides plan output"| node_plans
node_user -->|"explores and edits"| node_canvas
node_canvas -->|"edits elements"| node_element_api
node_user -->|"manages graphs"| node_graph_ui
node_graph_ui -.->|"creates and manages"| node_graph_api
node_user -->|"imports CSV"| node_csv_ui
node_csv_ui -.->|"uploads data"| node_csv_api
node_csv_api -.->|"stores temporary CSV"| node_csv_storage
node_csv_api -->|"loads graph data"| node_database
node_user -->|"requests assistance"| node_chat_ui
node_chat_ui -.->|"sends prompts"| node_chat_api
node_chat_api -.->|"uses model options"| node_models_api
node_user -->|"administers access"| node_settings
node_settings -.->|"manages users"| node_users_api
node_settings -->|"manages tokens"| node_tokens_ui
node_user -.->|"manages functions"| node_udf_ui
node_udf_ui -.->|"manages functions"| node_udf_api

click node_connection_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/components/ConnectionManager.tsx"
click node_auth "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/auth/%5B...nextauth%5D/options.ts"
click node_connection_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/connections/route.ts"
click node_editor "https://github.com/falkordb/falkordb-browser/blob/staging/app/components/EditorComponent.tsx"
click node_query_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/run-query.ts"
click node_canvas "https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/GraphView.tsx"
click node_table "https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/TableView.tsx"
click node_history "https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/QueryHistoryPanel.tsx"
click node_plans "https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/MetadataView.tsx"
click node_graph_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/route.ts"
click node_graph_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/components/CreateGraph.tsx"
click node_element_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/%5Belement%5D/route.ts"
click node_csv_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/components/graph/UploadGraph.tsx"
click node_csv_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/load-csv/route.ts"
click node_csv_storage "https://github.com/falkordb/falkordb-browser/blob/staging/app/lib/csv-storage.ts"
click node_chat_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/Chat.tsx"
click node_chat_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/chat/route.tsx"
click node_models_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/chat/models/route.ts"
click node_settings "https://github.com/falkordb/falkordb-browser/blob/staging/app/settings/page.tsx"
click node_users_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/user/route.ts"
click node_tokens_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/settings/tokens/PersonalAccessTokens.tsx"
click node_udf_ui "https://github.com/falkordb/falkordb-browser/blob/staging/app/udf/page.tsx"
click node_udf_api "https://github.com/falkordb/falkordb-browser/blob/staging/app/api/udf/route.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_connection_ui,node_auth,node_connection_api,node_user toneBlue
class node_editor,node_query_api,node_canvas,node_table,node_history,node_plans,node_database toneAmber
class node_graph_api,node_graph_ui,node_element_api,node_csv_ui,node_csv_api,node_csv_storage toneMint
class node_chat_ui,node_chat_api,node_models_api toneRose
class node_settings,node_users_api,node_tokens_ui,node_udf_ui,node_udf_api toneIndigo
```

## Components

### Connection and access

- [Connections](https://github.com/falkordb/falkordb-browser/blob/staging/app/components/ConnectionManager.tsx): `app/components/ConnectionManager.tsx`
- [Session and auth](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/auth/%5B...nextauth%5D/options.ts): `app/api/auth/[...nextauth]/options.ts`
- [Connection API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/connections/route.ts): `app/api/connections/route.ts`

### Query and exploration

- [Cypher editor](https://github.com/falkordb/falkordb-browser/blob/staging/app/components/EditorComponent.tsx): `app/components/EditorComponent.tsx`
- [Query execution](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/run-query.ts): `app/api/run-query.ts`
- [Graph canvas](https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/GraphView.tsx): `app/graph/GraphView.tsx`
- [Table view](https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/TableView.tsx): `app/graph/TableView.tsx`
- [Query history](https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/QueryHistoryPanel.tsx): `app/graph/QueryHistoryPanel.tsx`
- [Plans and metadata](https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/MetadataView.tsx): `app/graph/MetadataView.tsx`

### Graph management

- [Graph operations](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/route.ts): `app/api/graph/[graph]/route.ts`
- [Graph management UI](https://github.com/falkordb/falkordb-browser/blob/staging/app/components/CreateGraph.tsx): `app/components/CreateGraph.tsx`
- [Element editing API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/%5Belement%5D/route.ts): `app/api/graph/[graph]/[element]/route.ts`
- [CSV import UI](https://github.com/falkordb/falkordb-browser/blob/staging/app/components/graph/UploadGraph.tsx): `app/components/graph/UploadGraph.tsx`
- [CSV import API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/graph/%5Bgraph%5D/load-csv/route.ts): `app/api/graph/[graph]/load-csv/route.ts`
- [Temporary CSV storage](https://github.com/falkordb/falkordb-browser/blob/staging/app/lib/csv-storage.ts): `app/lib/csv-storage.ts`

### AI assistance

- [AI chat and tools](https://github.com/falkordb/falkordb-browser/blob/staging/app/graph/Chat.tsx): `app/graph/Chat.tsx`
- [AI chat API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/chat/route.tsx): `app/api/chat/route.tsx`
- [AI model discovery](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/chat/models/route.ts): `app/api/chat/models/route.ts`

### Administration

- [Settings](https://github.com/falkordb/falkordb-browser/blob/staging/app/settings/page.tsx): `app/settings/page.tsx`
- [Users and roles API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/user/route.ts): `app/api/user/route.ts`
- [Access tokens](https://github.com/falkordb/falkordb-browser/blob/staging/app/settings/tokens/PersonalAccessTokens.tsx): `app/settings/tokens/PersonalAccessTokens.tsx`
- [UDF management](https://github.com/falkordb/falkordb-browser/blob/staging/app/udf/page.tsx): `app/udf/page.tsx`
- [UDF API](https://github.com/falkordb/falkordb-browser/blob/staging/app/api/udf/route.ts): `app/api/udf/route.ts`

### Other components

- **User**
- **FalkorDB**

## Connections

- User → Connections: connects to (evidence: `README.md`)
- Connections → Connection API: manages connections (evidence: `app/components/ConnectionManager.tsx`)
- Connection API → Session and auth: uses session (evidence: `app/api/connections/route.ts`)
- User → Cypher editor: writes Cypher (evidence: `README.md`)
- Cypher editor → Query execution: submits query (evidence: `README.md`)
- Query execution → FalkorDB: runs Cypher (evidence: `README.md`)
- Query execution → Graph canvas: returns results (evidence: `README.md`)
- Query execution → Table view: returns results (evidence: `README.md`)
- Cypher editor → Query history: reviews history (evidence: `README.md`)
- Query execution → Plans and metadata: provides plan output (evidence: `README.md`)
- User → Graph canvas: explores and edits (evidence: `README.md`)
- Graph canvas → Element editing API: edits elements (evidence: `README.md`)
- User → Graph management UI: manages graphs (evidence: `README.md`)
- Graph management UI → Graph operations: creates and manages
- User → CSV import UI: imports CSV (evidence: `README.md`)
- CSV import UI → CSV import API: uploads data
- CSV import API → Temporary CSV storage: stores temporary CSV
- CSV import API → FalkorDB: loads graph data (evidence: `README.md`)
- User → AI chat and tools: requests assistance (evidence: `README.md`)
- AI chat and tools → AI chat API: sends prompts
- AI chat API → AI model discovery: uses model options
- User → Settings: administers access (evidence: `README.md`)
- Settings → Users and roles API: manages users
- Settings → Access tokens: manages tokens (evidence: `README.md`)
- User → UDF management: manages functions
- UDF management → UDF API: manages functions
