# embeddedos-org/edb architecture

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

- Interactive diagram: https://gitdiagram.com/embeddedos-org/edb
- Repository: https://github.com/embeddedos-org/edb
- Video tour (about a minute): https://gitdiagram.com/embeddedos-org/edb/video

## Overview

eDB combines a SQLite-backed multi-model database, a FastAPI service with authentication and security, an eBot query assistant, and a React database-manager UI. The main backend path is HTTP request → API route/dependencies → database facade → model-specific store → SQLite engine. The UI assembles table/query views and an eBot sidebar; the sampled UI database hook holds local state, so its connection to the backend is not demonstrated. Several subsystem links rely on README or SOURCE INDEX references rather than inspected implementation details.

Main entry points: [`src/edb/core/database.py`](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/database.py) (Database facade), [`src/edb/api/dependencies.py`](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/dependencies.py) (API services), [`src/App.tsx`](https://github.com/embeddedos-org/edb/blob/master/src/App.tsx) (App shell), [`src/edb/api/app.py`](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/app.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Database UI"]
  node_app_ui["App shell<br/>[App.tsx]"]
  node_table_browser["Table browser<br/>[TableList.tsx]"]
  node_table_editor["Table editor<br/>[TableView.tsx]"]
  node_query_editor["Query editor<br/>[QueryEditor.tsx]"]
  node_ui_state["UI database state<br/>[useDatabase.ts]"]
  node_ebot_sidebar["eBot sidebar<br/>[EBotSidebar.tsx]"]
  node_ebot_hook["eBot API hook<br/>[useEBot.ts]"]
end

subgraph group_api["HTTP API"]
  node_api_app["API application<br/>[app.py]"]
  node_sql_route["SQL endpoint<br/>[sql.py]"]
  node_model_routes["Model endpoints"]
  node_ebot_route["eBot endpoint<br/>[ebot.py]"]
  node_api_state["API services<br/>[dependencies.py]"]
  node_auth_routes["Authentication endpoints<br/>[auth.py]"]
end

subgraph group_security["Auth &amp; security"]
  node_jwt["JWT handling<br/>[jwt_handler.py]"]
  node_identity["Users and RBAC<br/>[users.py]"]
  node_audit["Audit logging<br/>[audit.py]"]
end

subgraph group_query["Query assistant"]
  node_query_parser["Query parser<br/>[parser.py]"]
  node_query_planner["Query planner<br/>[planner.py]"]
  node_translator["eBot translator<br/>[translator.py]"]
  node_llm["Optional LLM backend<br/>[llm_translator.py]"]
end

subgraph group_data["Database engine"]
  node_database["Database facade<br/>[database.py]"]
  node_relational["Relational store<br/>[relational.py]"]
  node_documents["Document store<br/>[document.py]"]
  node_keyvalue["Key-value store<br/>[keyvalue.py]"]
  node_graph["Graph store<br/>[graph.py]"]
  node_fts["Full-text search<br/>[fts.py]"]
  node_storage[("SQLite engine<br/>[engine.py]")]
end

node_user(("Database user"))
node_sqlite[("SQLite")]

node_user -->|"uses"| node_app_ui
node_app_ui -->|"renders"| node_table_browser
node_app_ui -->|"renders"| node_table_editor
node_app_ui -->|"renders"| node_query_editor
node_app_ui -->|"renders"| node_ebot_sidebar
node_app_ui -->|"uses"| node_ui_state
node_app_ui -->|"uses"| node_ebot_hook
node_table_browser -->|"reads and updates"| node_ui_state
node_table_editor -->|"updates rows"| node_ui_state
node_query_editor -->|"reads tables"| node_ui_state
node_ebot_sidebar -->|"requests queries"| node_ebot_hook
node_ebot_hook -.->|"calls eBot HTTP"| node_user
node_user -->|"sends requests"| node_api_app
node_api_app -->|"registers route"| node_sql_route
node_api_app -->|"registers routes"| node_model_routes
node_api_app -->|"registers route"| node_auth_routes
node_api_app -->|"registers route"| node_ebot_route
node_sql_route -->|"uses dependencies"| node_api_state
node_model_routes -->|"uses dependencies"| node_api_state
node_auth_routes -->|"uses dependencies"| node_api_state
node_ebot_route -->|"uses dependencies"| node_api_state
node_ebot_route -->|"translates requests"| node_translator
node_ebot_route -->|"parses queries"| node_query_parser
node_ebot_route -->|"plans queries"| node_query_planner
node_translator -.->|"may use"| node_llm
node_api_state -->|"creates"| node_database
node_api_state -->|"creates and verifies"| node_jwt
node_api_state -->|"creates"| node_identity
node_api_state -->|"creates"| node_audit
node_auth_routes -.->|"authenticates"| node_jwt
node_auth_routes -->|"manages users"| node_identity
node_sql_route -->|"queries"| node_database
node_model_routes -.->|"accesses stores"| node_database
node_query_planner -->|"executes plans"| node_database
node_database -->|"initializes"| node_relational
node_database -->|"initializes"| node_documents
node_database -->|"initializes"| node_keyvalue
node_database -->|"initializes"| node_graph
node_database -->|"initializes"| node_fts
node_relational -->|"uses"| node_storage
node_graph -->|"uses"| node_storage
node_database -->|"creates"| node_storage
node_storage -->|"stores data"| node_sqlite
node_audit -->|"writes audit records"| node_storage

click node_app_ui "https://github.com/embeddedos-org/edb/blob/master/src/App.tsx"
click node_table_browser "https://github.com/embeddedos-org/edb/blob/master/src/components/TableList.tsx"
click node_table_editor "https://github.com/embeddedos-org/edb/blob/master/src/components/TableView.tsx"
click node_query_editor "https://github.com/embeddedos-org/edb/blob/master/src/components/QueryEditor.tsx"
click node_ui_state "https://github.com/embeddedos-org/edb/blob/master/src/hooks/useDatabase.ts"
click node_ebot_sidebar "https://github.com/embeddedos-org/edb/blob/master/src/components/EBotSidebar.tsx"
click node_ebot_hook "https://github.com/embeddedos-org/edb/blob/master/src/hooks/useEBot.ts"
click node_api_app "https://github.com/embeddedos-org/edb/blob/master/src/edb/api/app.py"
click node_sql_route "https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/sql.py"
click node_model_routes "https://github.com/embeddedos-org/edb/tree/master/src/edb/api/routes"
click node_ebot_route "https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/ebot.py"
click node_api_state "https://github.com/embeddedos-org/edb/blob/master/src/edb/api/dependencies.py"
click node_auth_routes "https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/auth.py"
click node_jwt "https://github.com/embeddedos-org/edb/blob/master/src/edb/auth/jwt_handler.py"
click node_identity "https://github.com/embeddedos-org/edb/blob/master/src/edb/auth/users.py"
click node_audit "https://github.com/embeddedos-org/edb/blob/master/src/edb/security/audit.py"
click node_query_parser "https://github.com/embeddedos-org/edb/blob/master/src/edb/query/parser.py"
click node_query_planner "https://github.com/embeddedos-org/edb/blob/master/src/edb/query/planner.py"
click node_translator "https://github.com/embeddedos-org/edb/blob/master/src/edb/ebot/translator.py"
click node_llm "https://github.com/embeddedos-org/edb/blob/master/src/edb/ebot/llm_translator.py"
click node_database "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/database.py"
click node_relational "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/relational.py"
click node_documents "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/document.py"
click node_keyvalue "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/keyvalue.py"
click node_graph "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/graph.py"
click node_fts "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/fts.py"
click node_storage "https://github.com/embeddedos-org/edb/blob/master/src/edb/core/engine.py"

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_app_ui,node_table_browser,node_table_editor,node_query_editor,node_ui_state,node_ebot_sidebar,node_ebot_hook toneBlue
class node_api_app,node_sql_route,node_model_routes,node_ebot_route,node_api_state,node_auth_routes,node_user,node_sqlite toneAmber
class node_jwt,node_identity,node_audit toneMint
class node_query_parser,node_query_planner,node_translator,node_llm toneRose
class node_database,node_relational,node_documents,node_keyvalue,node_graph,node_fts,node_storage toneIndigo
```

## Components

### Database UI

- [App shell](https://github.com/embeddedos-org/edb/blob/master/src/App.tsx): `src/App.tsx`
- [Table browser](https://github.com/embeddedos-org/edb/blob/master/src/components/TableList.tsx): `src/components/TableList.tsx`
- [Table editor](https://github.com/embeddedos-org/edb/blob/master/src/components/TableView.tsx): `src/components/TableView.tsx`
- [Query editor](https://github.com/embeddedos-org/edb/blob/master/src/components/QueryEditor.tsx): `src/components/QueryEditor.tsx`
- [UI database state](https://github.com/embeddedos-org/edb/blob/master/src/hooks/useDatabase.ts): `src/hooks/useDatabase.ts`
- [eBot sidebar](https://github.com/embeddedos-org/edb/blob/master/src/components/EBotSidebar.tsx): `src/components/EBotSidebar.tsx`
- [eBot API hook](https://github.com/embeddedos-org/edb/blob/master/src/hooks/useEBot.ts): `src/hooks/useEBot.ts`

### HTTP API

- [API application](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/app.py): `src/edb/api/app.py`
- [SQL endpoint](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/sql.py): `src/edb/api/routes/sql.py`
- [Model endpoints](https://github.com/embeddedos-org/edb/tree/master/src/edb/api/routes): `src/edb/api/routes`
- [eBot endpoint](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/ebot.py): `src/edb/api/routes/ebot.py`
- [API services](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/dependencies.py): `src/edb/api/dependencies.py`
- [Authentication endpoints](https://github.com/embeddedos-org/edb/blob/master/src/edb/api/routes/auth.py): `src/edb/api/routes/auth.py`

### Auth & security

- [JWT handling](https://github.com/embeddedos-org/edb/blob/master/src/edb/auth/jwt_handler.py): `src/edb/auth/jwt_handler.py`
- [Users and RBAC](https://github.com/embeddedos-org/edb/blob/master/src/edb/auth/users.py): `src/edb/auth/users.py`
- [Audit logging](https://github.com/embeddedos-org/edb/blob/master/src/edb/security/audit.py): `src/edb/security/audit.py`

### Query assistant

- [Query parser](https://github.com/embeddedos-org/edb/blob/master/src/edb/query/parser.py): `src/edb/query/parser.py`
- [Query planner](https://github.com/embeddedos-org/edb/blob/master/src/edb/query/planner.py): `src/edb/query/planner.py`
- [eBot translator](https://github.com/embeddedos-org/edb/blob/master/src/edb/ebot/translator.py): `src/edb/ebot/translator.py`
- [Optional LLM backend](https://github.com/embeddedos-org/edb/blob/master/src/edb/ebot/llm_translator.py): `src/edb/ebot/llm_translator.py`

### Database engine

- [Database facade](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/database.py): `src/edb/core/database.py`
- [Relational store](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/relational.py): `src/edb/core/relational.py`
- [Document store](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/document.py): `src/edb/core/document.py`
- [Key-value store](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/keyvalue.py): `src/edb/core/keyvalue.py`
- [Graph store](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/graph.py): `src/edb/core/graph.py`
- [Full-text search](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/fts.py): `src/edb/core/fts.py`
- [SQLite engine](https://github.com/embeddedos-org/edb/blob/master/src/edb/core/engine.py): `src/edb/core/engine.py`

### Other components

- **Database user**
- **SQLite**

## Connections

- Database user → App shell: uses (evidence: `README.md`)
- App shell → Table browser: renders (evidence: `src/App.tsx`)
- App shell → Table editor: renders (evidence: `src/App.tsx`)
- App shell → Query editor: renders (evidence: `src/App.tsx`)
- App shell → eBot sidebar: renders (evidence: `src/App.tsx`)
- App shell → UI database state: uses (evidence: `src/App.tsx`)
- App shell → eBot API hook: uses (evidence: `src/App.tsx`)
- Table browser → UI database state: reads and updates (evidence: `src/components/TableList.tsx`)
- Table editor → UI database state: updates rows (evidence: `src/App.tsx`)
- Query editor → UI database state: reads tables (evidence: `src/components/QueryEditor.tsx`)
- eBot sidebar → eBot API hook: requests queries (evidence: `src/App.tsx`)
- eBot API hook → Database user: calls eBot HTTP (evidence: `src/hooks/useEBot.ts`)
- Database user → API application: sends requests (evidence: `README.md`)
- API application → SQL endpoint: registers route (evidence: `src/edb/api/app.py`)
- API application → Model endpoints: registers routes (evidence: `src/edb/api/app.py`)
- API application → Authentication endpoints: registers route (evidence: `src/edb/api/app.py`)
- API application → eBot endpoint: registers route (evidence: `src/edb/api/app.py`)
- SQL endpoint → API services: uses dependencies (evidence: `src/edb/api/routes/sql.py`)
- Model endpoints → API services: uses dependencies (evidence: `src/edb/api/routes/documents.py`)
- Authentication endpoints → API services: uses dependencies (evidence: `src/edb/api/routes/auth.py`)
- eBot endpoint → API services: uses dependencies (evidence: `src/edb/api/routes/ebot.py`)
- eBot endpoint → eBot translator: translates requests (evidence: `src/edb/api/routes/ebot.py`)
- eBot endpoint → Query parser: parses queries (evidence: `src/edb/api/routes/ebot.py`)
- eBot endpoint → Query planner: plans queries (evidence: `src/edb/api/routes/ebot.py`)
- eBot translator → Optional LLM backend: may use (evidence: `README.md`)
- API services → Database facade: creates (evidence: `src/edb/api/dependencies.py`)
- API services → JWT handling: creates and verifies (evidence: `src/edb/api/dependencies.py`)
- API services → Users and RBAC: creates (evidence: `src/edb/api/dependencies.py`)
- API services → Audit logging: creates (evidence: `src/edb/api/dependencies.py`)
- Authentication endpoints → JWT handling: authenticates
- Authentication endpoints → Users and RBAC: manages users (evidence: `src/edb/api/routes/auth.py`)
- SQL endpoint → Database facade: queries (evidence: `src/edb/api/routes/sql.py`)
- Model endpoints → Database facade: accesses stores
- Query planner → Database facade: executes plans (evidence: `src/edb/query/planner.py`)
- Database facade → Relational store: initializes (evidence: `src/edb/core/database.py`)
- Database facade → Document store: initializes (evidence: `src/edb/core/database.py`)
- Database facade → Key-value store: initializes (evidence: `src/edb/core/database.py`)
- Database facade → Graph store: initializes (evidence: `src/edb/core/database.py`)
- Database facade → Full-text search: initializes (evidence: `src/edb/core/database.py`)
- Relational store → SQLite engine: uses (evidence: `src/edb/core/relational.py`)
- Graph store → SQLite engine: uses (evidence: `src/edb/core/graph.py`)
- Database facade → SQLite engine: creates (evidence: `src/edb/core/database.py`)
- SQLite engine → SQLite: stores data (evidence: `src/edb/core/engine.py`)
- Audit logging → SQLite engine: writes audit records (evidence: `src/edb/security/audit.py`)