# csharikrishna/knowledgedb architecture

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

- Interactive diagram: https://gitdiagram.com/csharikrishna/knowledgedb
- Repository: https://github.com/csharikrishna/knowledgedb

## Overview

1. **Repo shape**
   - This is a monorepo centered on a Node.js backend plus multiple React clients and SDKs.
   - The core product is **KnowledgeDB**: a self-hosted, file-backed NoSQL DBaaS with graph, search, memory, webhook, and analytics features.

2. **Backend entry points**
   - `server/server.js` is the HTTP server bootstrap.
   - `server/app.js` holds the Express application wiring.
   - The backend is organized by concern: `routes` define endpoints, `controllers` handle request logic, `middleware` enforces security/validation, and `utils` contain the actual engines.

3. **Primary request path**
   - External clients hit Express routes under `/auth`, `/db`, `/search`, `/graph`, `/memory`, `/triggers`, `/webhooks`, `/vectors`, `/analytics`, and admin/public endpoints.
   - Routes delegate to controllers, which coordinate auth, data access, and higher-level behaviors like graph traversal or hybrid search.
   - Utility modules implement the domain logic; this keeps HTTP concerns separate from storage/search/graph mechanics.

4. **Persistence model**
   - The system uses **pure JSON file storage** rather than an external database, matching the “zero external dependencies” design in the README.
   - Supporting utilities like `fileHandler`, `documentHelper`, `indexManager`, and `queryEngine` imply a file-based document store with indexing and query support.
   - A `data/` directory is mentioned in the README as auto-created storage.

5. **Authentication and tenancy boundary**
   - `authController`, `jwtHelper`, and `jwtMiddleware` implement user auth with JWTs.
   - `apiKeyMiddleware` and `apiKeyGenerator` support scoped API keys for programmatic access.
   - `adminMiddleware` separates system administration from normal tenant usage.
   - This creates a clear boundary between end-user database operations and privileged admin/system operations.

6. **Document CRUD and database management**
   - `crudController` and `databaseController` cover database creation plus collection/document CRUD.
   - The public data model is database → collection → document, with support for version history and query-by-collection.
   - This is the base layer that everything else builds on: graph extraction, search indexing, memory, analytics, triggers, and webhooks all sit downstream of document writes.

7. **Knowledge graph, hybrid search, and vector-style features**
   - `graphEngine` and `graphController` provide traversal, path, search, and stats over the auto-built knowledge graph.
   - `bm25Engine`, `hybridSearch`, and `searchController` indicate keyword search fused with graph relevance scoring.
   - `vectorEngine` and `vectors` routes suggest embedding/vector-related functionality alongside the main search stack.
   - `enhancedSearchController` likely combines these into richer retrieval flows such as GraphRAG.

8. **AI memory and conversational retrieval**
   - `memoryController` and `memoryEngine` implement session-scoped memory storage and recall.
   - The architecture treats memory as a first-class backend subsystem, not just a client-side cache.
   - In practice, memory likely feeds GraphRAG or search relevance when generating context-aware responses.

9. **Realtime, triggers, and outbound delivery**
   - `sseManager` provides Server-Sent Events for live updates from the backend to clients.
   - `triggerEngine` and `triggerController` manage conditional event rules inside the system.
   - `webhookDispatcher` and `webhookController` push signed webhook deliveries outward, so the backend can notify external systems when data changes.

10. **Analytics and graph-oriented reporting**
    - `analyticsEngine` and `analyticsController` provide aggregation-style reporting such as groupBy, sum, avg, min/max, and time series.
    - This is a separate read/compute path from CRUD and search, but it operates on the same stored documents.
    - `analytics` is exposed as an API capability rather than a background batch job.

11. **Frontend surfaces**
    - `web-explorer/` is the primary product UI in the README: a React app with welcome, login, dashboard, graph explorer, search, memory browser, GraphRAG tester, and admin panel pages.
    - `admin-dashboard/` and `user-dashboard/` are additional React apps present in the repo and appear to be legacy or alternative dashboards.
    - These UIs talk to the backend through `src/services/api.js` clients and are separated by role and feature area.

12. **SDK and programmatic access**
    - `sdk/knowledgedb.js` and `sdk/knowledgedb.py` expose the backend as a consumable client library for Node.js and Python.
    - This makes the backend usable both interactively through the web UI and directly from application code.

13. **Operational and delivery concerns**
    - `Dockerfile`, `docker-compose.yml`, and `render.yaml` show the project is packaged for containerized and platform deployment.
    - `scripts/seed.js`, `scripts/seed-advanced.js`, and `scripts/integration-test.js` support demo data and verification.
    - The surrounding docs focus heavily on deployment, readiness, and integration, indicating the repo is intended to be run as a self-hosted product rather than a library only.

14. **Overall architecture diagram takeaway**
    - The key diagram should show: clients/SDKs → Express API layer → controllers → core engines/utils → JSON file storage, with side paths for graph indexing, search/memory/analytics, and outbound SSE/webhooks.
    - Admin functions and user functions share the same backend but are separated by auth, API keys, and middleware-based authorization.

Main entry points: [`server/app.js`](https://github.com/csharikrishna/knowledgedb/blob/main/server/app.js) (Express App), [`server/utils/fileHandler.js`](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/fileHandler.js) (File Storage), [`server/controllers/crudController.js`](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/crudController.js) (Data Ctrl), [`server/routes/search.js`](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/search.js) (Search & Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_web_explorer["Web Explorer<br/>react app<br/>[App.jsx]"]
  node_admin_dashboard["Admin Dashboard<br/>react app<br/>[App.js]"]
  node_user_dashboard["User Dashboard<br/>react app<br/>[App.js]"]
  node_sdk_node["Node SDK<br/>client sdk<br/>[knowledgedb.js]"]
  node_sdk_python["Python SDK<br/>client sdk<br/>[knowledgedb.py]"]
end

subgraph group_backend["Backend"]
  node_server_boot["Server Boot<br/>http bootstrap<br/>[server.js]"]
  node_express_app["Express App<br/>api wiring<br/>[app.js]"]
  node_auth_routes["Auth API<br/>route layer<br/>[auth.js]"]
  node_data_routes["Data API<br/>route layer<br/>[database.js]"]
  node_search_graph_routes["Search & Graph<br/>route layer<br/>[search.js]"]
  node_memory_routes["Memory API<br/>route layer<br/>[memory.js]"]
  node_events_routes["Events API<br/>route layer<br/>[triggers.js]"]
  node_analytics_routes["Analytics API<br/>route layer<br/>[analytics.js]"]
  node_admin_routes["Admin API<br/>route layer<br/>[admin.js]"]
  node_auth_ctrl["Auth Ctrl<br/>controller<br/>[authController.js]"]
  node_data_ctrl["Data Ctrl<br/>controller<br/>[crudController.js]"]
  node_search_ctrl["Search Ctrl<br/>controller"]
  node_graph_ctrl["Graph Ctrl<br/>controller<br/>[graphController.js]"]
  node_memory_ctrl["Memory Ctrl<br/>controller"]
  node_analytics_ctrl["Analytics Ctrl<br/>controller"]
  node_admin_ctrl["Admin Ctrl<br/>controller<br/>[adminController.js]"]
  node_search_engine{{"Search Engine<br/>query engine<br/>[hybridSearch.js]"}}
  node_graph_engine{{"Graph Engine<br/>[graphEngine.js]"}}
  node_memory_engine{{"Memory Engine<br/>memory store<br/>[memoryEngine.js]"}}
  node_analytics_engine{{"Analytics Engine<br/>aggregation engine<br/>[analyticsEngine.js]"}}
  node_event_outbound{{"Triggers & Webhooks<br/>event dispatch"}}
end

subgraph group_storage["Storage"]
  node_storage_core[("File Storage<br/>json storage<br/>[fileHandler.js]")]
  node_indexing_core{{"Indexing Core<br/>index/query<br/>[indexManager.js]"}}
end

subgraph group_ops["Ops"]
  node_deploy_pack["Deploy Pack<br/>ops"]
  node_seed_tools["Seed Tools<br/>ops scripts<br/>[seed.js]"]
end

node_web_explorer -->|"API calls"| node_express_app
node_admin_dashboard -->|"API calls"| node_express_app
node_user_dashboard -->|"API calls"| node_express_app
node_sdk_node -->|"programmatic access"| node_express_app
node_sdk_python -->|"programmatic access"| node_express_app
node_server_boot -->|"starts"| node_express_app
node_express_app -->|"mounts"| node_auth_routes
node_express_app -->|"mounts"| node_data_routes
node_express_app -->|"mounts"| node_search_graph_routes
node_express_app -->|"mounts"| node_memory_routes
node_express_app -->|"mounts"| node_events_routes
node_express_app -->|"mounts"| node_analytics_routes
node_express_app -->|"mounts"| node_admin_routes
node_auth_routes -->|"delegates"| node_auth_ctrl
node_data_routes -->|"delegates"| node_data_ctrl
node_search_graph_routes -->|"delegates"| node_search_ctrl
node_search_graph_routes -->|"delegates"| node_graph_ctrl
node_memory_routes -->|"delegates"| node_memory_ctrl
node_events_routes -.->|"delegates"| node_admin_ctrl
node_analytics_routes -->|"delegates"| node_analytics_ctrl
node_admin_routes -->|"delegates"| node_admin_ctrl
node_auth_ctrl -->|"auth state"| node_storage_core
node_data_ctrl -->|"reads/writes"| node_storage_core
node_data_ctrl -->|"updates"| node_indexing_core
node_search_ctrl -->|"uses"| node_search_engine
node_search_engine -->|"queries"| node_indexing_core
node_graph_ctrl -->|"uses"| node_graph_engine
node_graph_engine -->|"derives from"| node_storage_core
node_memory_ctrl -->|"uses"| node_memory_engine
node_memory_engine -->|"persists"| node_storage_core
node_analytics_ctrl -->|"uses"| node_analytics_engine
node_analytics_engine -->|"reads"| node_storage_core
node_admin_ctrl -->|"admin reads/writes"| node_storage_core
node_data_ctrl -.->|"emits"| node_event_outbound
node_event_outbound -.->|"tracks state"| node_storage_core
node_deploy_pack -.->|"packages"| node_server_boot
node_seed_tools -.->|"initializes"| node_storage_core

click node_web_explorer "https://github.com/csharikrishna/knowledgedb/blob/main/web-explorer/src/App.jsx"
click node_admin_dashboard "https://github.com/csharikrishna/knowledgedb/blob/main/admin-dashboard/src/App.js"
click node_user_dashboard "https://github.com/csharikrishna/knowledgedb/blob/main/user-dashboard/src/App.js"
click node_sdk_node "https://github.com/csharikrishna/knowledgedb/blob/main/sdk/knowledgedb.js"
click node_sdk_python "https://github.com/csharikrishna/knowledgedb/blob/main/sdk/knowledgedb.py"
click node_server_boot "https://github.com/csharikrishna/knowledgedb/blob/main/server/server.js"
click node_express_app "https://github.com/csharikrishna/knowledgedb/blob/main/server/app.js"
click node_auth_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/auth.js"
click node_data_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/database.js"
click node_search_graph_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/search.js"
click node_memory_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/memory.js"
click node_events_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/triggers.js"
click node_analytics_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/analytics.js"
click node_admin_routes "https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/admin.js"
click node_auth_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/authController.js"
click node_data_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/crudController.js"
click node_search_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/searchController.js"
click node_graph_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/graphController.js"
click node_memory_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/memoryController.js"
click node_analytics_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/analyticsController.js"
click node_admin_ctrl "https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/adminController.js"
click node_search_engine "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/hybridSearch.js"
click node_graph_engine "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/graphEngine.js"
click node_memory_engine "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/memoryEngine.js"
click node_analytics_engine "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/analyticsEngine.js"
click node_event_outbound "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/webhookDispatcher.js"
click node_storage_core "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/fileHandler.js"
click node_indexing_core "https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/indexManager.js"
click node_deploy_pack "https://github.com/csharikrishna/knowledgedb/tree/main/Dockerfile"
click node_seed_tools "https://github.com/csharikrishna/knowledgedb/blob/main/scripts/seed.js"

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_web_explorer,node_admin_dashboard,node_user_dashboard,node_sdk_node,node_sdk_python toneBlue
class node_server_boot,node_express_app,node_auth_routes,node_data_routes,node_search_graph_routes,node_memory_routes,node_events_routes,node_analytics_routes,node_admin_routes,node_auth_ctrl,node_data_ctrl,node_search_ctrl,node_graph_ctrl,node_memory_ctrl,node_analytics_ctrl,node_admin_ctrl,node_search_engine,node_graph_engine,node_memory_engine,node_analytics_engine,node_event_outbound toneAmber
class node_storage_core,node_indexing_core toneMint
class node_deploy_pack,node_seed_tools toneRose
```

## Components

### Clients

Human-facing apps and programmatic SDKs

- [Web Explorer](https://github.com/csharikrishna/knowledgedb/blob/main/web-explorer/src/App.jsx): react app · Primary product UI with dashboard, search, graph, memory, and GraphRAG surfaces · `web-explorer/src/App.jsx`
- [Admin Dashboard](https://github.com/csharikrishna/knowledgedb/blob/main/admin-dashboard/src/App.js): react app · Admin-focused React console for system and data oversight · `admin-dashboard/src/App.js`
- [User Dashboard](https://github.com/csharikrishna/knowledgedb/blob/main/user-dashboard/src/App.js): react app · User account and database management UI · `user-dashboard/src/App.js`
- [Node SDK](https://github.com/csharikrishna/knowledgedb/blob/main/sdk/knowledgedb.js): client sdk · JavaScript client library for programmatic access · `sdk/knowledgedb.js`
- [Python SDK](https://github.com/csharikrishna/knowledgedb/blob/main/sdk/knowledgedb.py): client sdk · Python client library for programmatic access · `sdk/knowledgedb.py`

### Backend

Node.js API, authorization, and domain engines

- [Server Boot](https://github.com/csharikrishna/knowledgedb/blob/main/server/server.js): http bootstrap · HTTP server entrypoint · `server/server.js`
- [Express App](https://github.com/csharikrishna/knowledgedb/blob/main/server/app.js): api wiring · Express application setup and middleware wiring · `server/app.js`
- [Auth API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/auth.js): route layer · Login, signup, JWT flows, and session boundaries · `server/routes/auth.js`
- [Data API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/database.js): route layer · Database, CRUD, and public data endpoints · `server/routes/database.js`
- [Search & Graph](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/search.js): route layer · Search, graph, enhanced retrieval, and vector endpoints · `server/routes/search.js`
- [Memory API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/memory.js): route layer · Session memory endpoints · `server/routes/memory.js`
- [Events API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/triggers.js): route layer · Triggers and webhook endpoints · `server/routes/triggers.js`
- [Analytics API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/analytics.js): route layer · Analytic query endpoints · `server/routes/analytics.js`
- [Admin API](https://github.com/csharikrishna/knowledgedb/blob/main/server/routes/admin.js): route layer · Privileged system administration endpoints · `server/routes/admin.js`
- [Auth Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/authController.js): controller · Authentication and account request handling · `server/controllers/authController.js`
- [Data Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/crudController.js): controller · Database and document CRUD orchestration · `server/controllers/crudController.js`
- [Search Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/searchController.js): controller · Keyword, hybrid, and enhanced search orchestration · `server/controllers/searchController.js`
- [Graph Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/graphController.js): controller · Graph traversal, path, and stats requests · `server/controllers/graphController.js`
- [Memory Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/memoryController.js): controller · Session memory recall and persistence requests · `server/controllers/memoryController.js`
- [Analytics Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/analyticsController.js): controller · Aggregation and reporting requests · `server/controllers/analyticsController.js`
- [Admin Ctrl](https://github.com/csharikrishna/knowledgedb/blob/main/server/controllers/adminController.js): controller · Privileged admin operations · `server/controllers/adminController.js`
- [Search Engine](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/hybridSearch.js): query engine · BM25, hybrid ranking, and query evaluation · `server/utils/hybridSearch.js`
- [Graph Engine](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/graphEngine.js): graph engine · Knowledge graph construction and traversal · `server/utils/graphEngine.js`
- [Memory Engine](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/memoryEngine.js): memory store · Conversation and session memory handling · `server/utils/memoryEngine.js`
- [Analytics Engine](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/analyticsEngine.js): aggregation engine · GroupBy and metric computations over stored data · `server/utils/analyticsEngine.js`
- [Triggers & Webhooks](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/webhookDispatcher.js): event dispatch · Trigger evaluation and outbound webhook delivery · `server/utils/webhookDispatcher.js`

### Storage

File-backed persistence and indexing

- [File Storage](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/fileHandler.js): json storage · File-backed document persistence and helpers · `server/utils/fileHandler.js`
- [Indexing Core](https://github.com/csharikrishna/knowledgedb/blob/main/server/utils/indexManager.js): index/query · Document helpers, indexes, and query execution · `server/utils/indexManager.js`

### Ops

Packaging, seeding, and verification

- [Deploy Pack](https://github.com/csharikrishna/knowledgedb/tree/main/Dockerfile): ops · Container and platform deployment definitions · `Dockerfile`
- [Seed Tools](https://github.com/csharikrishna/knowledgedb/blob/main/scripts/seed.js): ops scripts · Demo data loading and integration verification · `scripts/seed.js`

## Connections

- Web Explorer → Express App: API calls · UI clients call the backend API
- Admin Dashboard → Express App: API calls · Admin console uses the same backend
- User Dashboard → Express App: API calls · User console uses the same backend
- Node SDK → Express App: programmatic access · Node SDK wraps backend endpoints
- Python SDK → Express App: programmatic access · Python SDK wraps backend endpoints
- Server Boot → Express App: starts · HTTP server boots the Express app
- Express App → Auth API: mounts · Route wiring for auth flows
- Express App → Data API: mounts · Route wiring for database and CRUD
- Express App → Search & Graph: mounts · Route wiring for search, graph, and vectors
- Express App → Memory API: mounts · Route wiring for memory endpoints
- Express App → Events API: mounts · Route wiring for triggers and webhooks
- Express App → Analytics API: mounts · Route wiring for analytics endpoints
- Express App → Admin API: mounts · Route wiring for admin endpoints
- Auth API → Auth Ctrl: delegates · Auth routes delegate request logic
- Data API → Data Ctrl: delegates · CRUD routes delegate request logic
- Search & Graph → Search Ctrl: delegates · Search routes delegate request logic
- Search & Graph → Graph Ctrl: delegates · Graph routes delegate request logic
- Memory API → Memory Ctrl: delegates · Memory routes delegate request logic
- Events API → Admin Ctrl: delegates · Event-related administrative flows and dispatch coordination
- Analytics API → Analytics Ctrl: delegates · Analytics routes delegate request logic
- Admin API → Admin Ctrl: delegates · Admin routes delegate request logic
- Auth Ctrl → File Storage: auth state · Users and tokens are persisted in file-backed storage
- Data Ctrl → File Storage: reads/writes · Document CRUD uses JSON file persistence
- Data Ctrl → Indexing Core: updates · Writes refresh indexes and query structures
- Search Ctrl → Search Engine: uses · Search controller runs retrieval and ranking
- Search Engine → Indexing Core: queries · Search uses indexes and query execution
- Graph Ctrl → Graph Engine: uses · Graph controller runs traversal and stats
- Graph Engine → File Storage: derives from · Graph is built from stored documents
- Memory Ctrl → Memory Engine: uses · Memory controller stores and recalls context
- Memory Engine → File Storage: persists · Memory is stored in file-backed data
- Analytics Ctrl → Analytics Engine: uses · Analytics controller computes aggregates
- Analytics Engine → File Storage: reads · Analytics operates on stored documents
- Admin Ctrl → File Storage: admin reads/writes · Admin operations inspect and manage stored data
- Data Ctrl → Triggers & Webhooks: emits · Writes can trigger downstream events and webhooks
- Triggers & Webhooks → File Storage: tracks state · Trigger and delivery metadata is backed by files
- Deploy Pack → Server Boot: packages · Containerization packages the backend server
- Seed Tools → File Storage: initializes · Seed scripts populate the file-backed store
