How vinaykhanchi712/onql-vk works
Project Type and Purpose
• ONQL is a backend‐focused, API‐first, context‐aware database engine written in Go with a custom DSL parser, evaluator, pluggable protocol extensions (in Python), and support for multiple storage backends.
• Its goal is to allow clients and services to query related data without manual joins by using an “Object Notation Query Language” and context‐aware protocols.
File Structure Analysis
• cmd/server: Entry point – starts the TCP/HTTP server.
• config: Environment and configuration loader.
• router: Routes incoming DSL/API requests to handlers (CUD, DSL, streaming, extensions).
• dsl: Parser (lexer, parser) and evaluator of the ONQL language.
• database & storemanager: Schema definitions, CRUD operations, validation, setup; abstractions over physical stores.
• engine: Adapters for BadgerDB, CacheDB, NATS messaging.
• extensions: Python‐based protocol and schema plugins that define context and relations via JSON + request handlers.
• server: Low‐level TCP server implementation.
• utils: Shared helpers (ULID, string utilities).
• docker & .github: Deployment and CI configuration.
Key README Insights
• Emphasizes a layered, plugin‐ready architecture: Core engine interprets DSL → consults protocol definitions → executes against storage backends → returns results via API.
• Supports context‐aware security, migrations, CLI, drivers, ORMs, and plugin SDK.
Main Components
a. Client / CLI / API Consumer
• Sends ONQL queries or commands
b. Entry Server Layer
• cmd/server → server/tcp_server.go
• router/setup.go & route.go
c. DSL Subsystem
• parser (dsl/parser)
• evaluator (dsl/evaluator)
d. Protocol Manager / Extension Host
• extensions/protocol & extensions/schema (JSON protocol files + Python handlers)
e. Query Engine & Validation
• database/* (CRUD, schema, validation)
• storemanager/* (data synchronization, indexing)
f. Storage Backends
• engine/badgerdb.go
• engine/cashedb.go
• message broker: engine/nats.go
g. Configuration
• config/config.go & .env files
h. Deployment
• docker/compose.build.yml, Dockerfiles, stack.yaml
Relationships & Interactions
• Client → Server Layer (TCP/HTTP) → Router
• Router → DSL Parser → DSL Evaluator
• Evaluator → Protocol Manager (loads JSON, calls Python request_handler via IPC/HTTP)
• Evaluator → Query Engine → Database Layer → Storemanager → Storage Adapters
• Engine adapters read/write to BadgerDB or in‐memory cache, publish events to NATS
• Results bubble back through evaluator → router → client
Architectural Patterns & Principles
• Layered Architecture: clear separation of transport, routing, DSL, engine, storage.
• Plugin/Extension Pattern: protocol and schema extensibility via external Python services.
• Adapter Pattern: storage backends abstracted behind engine/adapter interfaces.
• Microservice‐ready: NATS messaging for eventing, Docker for containerization.
Essential Elements to Capture
• Config loader feeding all layers with environment values.
• Router’s multiple handlers: CUD, DSL queries, extensions, streams.
• Flow from client to persistent storage and back.
• Extension protocols as first‐class citizens in the request pipeline.