# phucvohoai/njsql architecture

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

- Interactive diagram: https://gitdiagram.com/phucvohoai/njsql
- Repository: https://github.com/phucvohoai/njsql

## Overview

NJSQL is a standalone Java database server. Users connect through its CLI or network interfaces, authenticate, select a database, and issue SQL; the engine supports relational constraints over NSON tables. Separate capabilities cover real-time table updates, indexing, account permissions, and Git-inspired clone/push and conflict workflows. The excerpts show gRPC dispatch and parts of sharing, storage, and management; unsampled server and handler implementations limit claims about their internal wiring.

Main entry points: [`src/main/java/njsql/grpc/NJSQLGrpcService.java`](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/grpc/NJSQLGrpcService.java) (gRPC service), [`src/main/java/njsql/NJSQL.java`](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/NJSQL.java) (NJSQL CLI), [`src/main/java/njsql/server/ShareServer.java`](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/server/ShareServer.java) (Share server), [`src/main/java/njsql/core/TableUtils.java`](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/TableUtils.java) (Table operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and APIs"]
  node_cli["NJSQL CLI<br/>[NJSQL.java]"]
  node_server["HTTP server<br/>[NJSQLServer.java]"]
  node_grpc["gRPC service"]
  node_proto["gRPC contract<br/>[njsql.proto]"]
end

subgraph group_query["Query and tables"]
  node_executor["SQL executor<br/>[NJSQLExecutor.java]"]
  node_select["SELECT handler<br/>[SelectHandler.java]"]
  node_insert["INSERT handler<br/>[InsertHandler.java]"]
  node_update["UPDATE handler<br/>[UpdateHandler.java]"]
  node_delete["DELETE handler<br/>[DeleteHandler.java]"]
  node_tableops["Table operations<br/>[TableUtils.java]"]
  node_realtime["Realtime tables"]
end

subgraph group_data["Storage and indexing"]
  node_tabledata[("NSON database files<br/>[NSON.java]")]
  node_nsonobject["NSON objects<br/>[NsonObject.java]"]
  node_indexes["Index manager<br/>[IndexManager.java]"]
  node_btree["B-tree indexes"]
end

subgraph group_security["Identity and permissions"]
  node_auth["Authentication<br/>[Authenticator.java]"]
  node_users["User manager<br/>[UserManager.java]"]
  node_permissions["Permission manager"]
end

subgraph group_sharing["Version sharing"]
  node_share["Share server<br/>[ShareServer.java]"]
  node_commits["Commit manager<br/>[CommitManager.java]"]
  node_clone["Clone handler<br/>[CloneHandler.java]"]
  node_push["Push handler<br/>[PushHandler.java]"]
end

node_user(("Database user"))
node_remote(("Remote database user"))

node_user -->|"issues commands"| node_cli
node_cli -->|"authenticates"| node_auth
node_cli -->|"starts"| node_server
node_user -->|"sends requests"| node_server
node_user -.->|"sends queries"| node_grpc
node_proto -->|"defines RPCs"| node_grpc
node_grpc -->|"checks login"| node_users
node_grpc -->|"dispatches SELECT"| node_select
node_grpc -->|"dispatches INSERT"| node_insert
node_grpc -->|"dispatches UPDATE"| node_update
node_grpc -->|"dispatches DELETE"| node_delete
node_grpc -->|"registers listeners"| node_realtime
node_auth -->|"checks accounts"| node_users
node_permissions -->|"updates accounts"| node_users
node_executor -->|"dispatches queries"| node_select
node_select -->|"reads tables"| node_tableops
node_insert -->|"writes rows"| node_tableops
node_update -->|"changes rows"| node_tableops
node_delete -->|"removes rows"| node_tableops
node_realtime -->|"flushes changes"| node_tabledata
node_nsonobject -->|"encodes data"| node_tabledata
node_tableops -.->|"maintains indexes"| node_indexes
node_indexes -.->|"optional B-tree"| node_btree
node_cli -->|"runs clone"| node_clone
node_cli -->|"runs push"| node_push
node_clone -->|"requests database files"| node_share
node_push -->|"submits changes"| node_share
node_share -->|"computes diffs"| node_commits
node_share -->|"serves requests"| node_remote
node_remote -->|"sends changes"| node_share

click node_cli "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/NJSQL.java"
click node_server "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/server/NJSQLServer.java"
click node_grpc "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/grpc/NJSQLGrpcService.java"
click node_proto "https://github.com/phucvohoai/njsql/blob/main/src/main/proto/njsql.proto"
click node_executor "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/NJSQLExecutor.java"
click node_select "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/SelectHandler.java"
click node_insert "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/InsertHandler.java"
click node_update "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/UpdateHandler.java"
click node_delete "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/DeleteHandler.java"
click node_tableops "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/TableUtils.java"
click node_realtime "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/RealtimeTableManager.java"
click node_tabledata "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/nson/NSON.java"
click node_nsonobject "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/nson/NsonObject.java"
click node_indexes "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/IndexManager.java"
click node_btree "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/indexing/BTreeIndexManager.java"
click node_auth "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/Authenticator.java"
click node_users "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/UserManager.java"
click node_permissions "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/PermissionManager.java"
click node_share "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/server/ShareServer.java"
click node_commits "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/CommitManager.java"
click node_clone "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/CloneHandler.java"
click node_push "https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/PushHandler.java"

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_cli,node_server,node_grpc,node_proto toneBlue
class node_executor,node_select,node_insert,node_update,node_delete,node_tableops,node_realtime,node_user,node_remote toneAmber
class node_tabledata,node_nsonobject,node_indexes,node_btree toneMint
class node_auth,node_users,node_permissions toneRose
class node_share,node_commits,node_clone,node_push toneIndigo
```

## Components

### Access and APIs

- [NJSQL CLI](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/NJSQL.java): `src/main/java/njsql/NJSQL.java`
- [HTTP server](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/server/NJSQLServer.java): `src/main/java/njsql/server/NJSQLServer.java`
- [gRPC service](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/grpc/NJSQLGrpcService.java): `src/main/java/njsql/grpc/NJSQLGrpcService.java`
- [gRPC contract](https://github.com/phucvohoai/njsql/blob/main/src/main/proto/njsql.proto): `src/main/proto/njsql.proto`

### Query and tables

- [SQL executor](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/NJSQLExecutor.java): `src/main/java/njsql/core/NJSQLExecutor.java`
- [SELECT handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/SelectHandler.java): `src/main/java/njsql/core/SelectHandler.java`
- [INSERT handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/InsertHandler.java): `src/main/java/njsql/core/InsertHandler.java`
- [UPDATE handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/UpdateHandler.java): `src/main/java/njsql/core/UpdateHandler.java`
- [DELETE handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/DeleteHandler.java): `src/main/java/njsql/core/DeleteHandler.java`
- [Table operations](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/TableUtils.java): `src/main/java/njsql/core/TableUtils.java`
- [Realtime tables](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/RealtimeTableManager.java): `src/main/java/njsql/core/RealtimeTableManager.java`

### Storage and indexing

- [NSON database files](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/nson/NSON.java): `src/main/java/njsql/nson/NSON.java`
- [NSON objects](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/nson/NsonObject.java): `src/main/java/njsql/nson/NsonObject.java`
- [Index manager](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/IndexManager.java): `src/main/java/njsql/core/IndexManager.java`
- [B-tree indexes](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/indexing/BTreeIndexManager.java): `src/main/java/njsql/indexing/BTreeIndexManager.java`

### Identity and permissions

- [Authentication](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/Authenticator.java): `src/main/java/njsql/core/Authenticator.java`
- [User manager](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/UserManager.java): `src/main/java/njsql/core/UserManager.java`
- [Permission manager](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/PermissionManager.java): `src/main/java/njsql/core/PermissionManager.java`

### Version sharing

- [Share server](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/server/ShareServer.java): `src/main/java/njsql/server/ShareServer.java`
- [Commit manager](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/CommitManager.java): `src/main/java/njsql/core/CommitManager.java`
- [Clone handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/CloneHandler.java): `src/main/java/njsql/core/CloneHandler.java`
- [Push handler](https://github.com/phucvohoai/njsql/blob/main/src/main/java/njsql/core/PushHandler.java): `src/main/java/njsql/core/PushHandler.java`

### Other components

- **Database user**
- **Remote database user**

## Connections

- Database user → NJSQL CLI: issues commands
- NJSQL CLI → Authentication: authenticates
- NJSQL CLI → HTTP server: starts
- Database user → HTTP server: sends requests
- Database user → gRPC service: sends queries
- gRPC contract → gRPC service: defines RPCs
- gRPC service → User manager: checks login
- gRPC service → SELECT handler: dispatches SELECT
- gRPC service → INSERT handler: dispatches INSERT
- gRPC service → UPDATE handler: dispatches UPDATE
- gRPC service → DELETE handler: dispatches DELETE
- gRPC service → Realtime tables: registers listeners
- Authentication → User manager: checks accounts
- Permission manager → User manager: updates accounts
- SQL executor → SELECT handler: dispatches queries
- SELECT handler → Table operations: reads tables
- INSERT handler → Table operations: writes rows
- UPDATE handler → Table operations: changes rows
- DELETE handler → Table operations: removes rows
- Realtime tables → NSON database files: flushes changes
- NSON objects → NSON database files: encodes data
- Table operations → Index manager: maintains indexes
- Index manager → B-tree indexes: optional B-tree
- NJSQL CLI → Clone handler: runs clone
- NJSQL CLI → Push handler: runs push
- Clone handler → Share server: requests database files
- Push handler → Share server: submits changes
- Share server → Commit manager: computes diffs
- Share server → Remote database user: serves requests
- Remote database user → Share server: sends changes