# EPIZO Node
## **EPIZO Node — Technical Architecture (Deep Dive)**
### **1. Core Definition (Refined)**
An **EPIZO Node** is a *self-contained distributed runtime unit* that runs a collection of offline-capable services on a single host machine and exposes them through a unified local interface.
It simultaneously acts as:
* **Application Host** → Runs multiple services (LLM, maps, notes, etc.)
* **Data Store** → Stores all local data (ZIM, vectors, KV, files)
* **API Gateway** → Single entry point (HTTP + SSE)
* **Service Orchestrator** → Manages service lifecycle & workloads
* **Offline Knowledge Engine** → Provides AI + knowledge without internet
***
### **2. Architectural Layers (Based on Diagram)**
#### **2.1 Command Center (Control Plane)**
**Components:**
* AdonisJS v6 backend
* React 19 UI (via Inertia)
* SSE (real-time events)
* BullMQ client
**Responsibilities:**
* Route user requests → appropriate services
* Provide unified UI/dashboard
* Manage workflows (AI queries, indexing, downloads)
* Basic observability (logs, status, lightweight metrics)
**Primary port:**
```
:8080 (HTTP + SSE)
```
**Key Insight:**\
The Command Center is not just a UI — it is the **control plane** of the entire node.
***
#### **2.2 Service Layer (Execution Plane)**
A set of modular services running as containers or processes:
**AI & Data Processing**
* Ollama → LLM inference
* CyberChef → data transformation
* Qdrant → vector database (RAG engine)
**Knowledge & Content**
* Kiwix → offline ZIM library
* Kolibri → education platform
* FlatNotes → local note system
**Geo & Utilities**
* ProtoMaps → offline maps
***
#### **2.3 Storage Layer (Data Plane)**
| Type | Function |
| ------------------ | ---------------------------- |
| ZIM | Offline knowledge base |
| Vector DB (Qdrant) | Embeddings & semantic search |
| KV (Redis) | Queue + cache |
| Filesystem | Models, documents, maps |
**Characteristics:**
* Fully local
* No external dependencies
* Optimized for read-heavy workloads
***
#### **2.4 Queue & Background System**
**Redis + BullMQ Workers**
Handles:
* Model downloads
* Embedding generation
* Indexing
* Benchmarking
* File processing
**Execution Model:**
* Workers run as separate processes
* Horizontally scalable
* Async-first architecture
**Key Insight:**\
This is the **hidden compute layer** that makes the node dynamic and responsive.
***
#### **2.5 Install & Runtime Layer**
**Components:**
* `install_epizo.sh`
* `entrypoint.sh`
* Sidecars:
* updater
* disk collector
**Responsibilities:**
* Node bootstrapping
* Dependency management
* Self-updates
* Resource cleanup
***
### **3. Execution Model (Detailed)**
#### **3.1 Hybrid Orchestration Model**
Combination of:
* Process-based orchestration
* Containerized services
* Queue-driven async execution
***
#### **3.2 Request Flow**
```
User → Command Center → Service Router → Target Service
↓
Queue (optional)
↓
Worker Execution
↓
Result → UI (SSE)
```
***
#### **3.3 Execution Modes**
**1. Direct (Synchronous)**
* Fast queries
* Immediate response
* Example: search, read note
**2. Async (Queue-Based)**
* Heavy workloads
* Background processing
* Example: embeddings, model downloads
**3. Streaming (SSE)**
* Real-time output
* Example: LLM token streaming
***
### **4. Node Characteristics**
#### **4.1 Offline-First**
* No internet required for core operations
* All dependencies can be locally cached
#### **4.2 Modular**
* Services can be added/removed
* Plug-and-play architecture
#### **4.3 Portable**
Runs on:
* Laptop
* Server
* Edge device
* Air-gapped environments
#### **4.4 Self-Sufficient**
* No cloud dependency
* Full stack contained in a single node
***
### **5. Internal Abstractions**
#### **5.1 Service Provider Model**
Each service is abstracted as:
```
Provider {
start()
stop()
health()
execute()
}
```
***
#### **5.2 Unified API Layer**
All services are exposed via:
```
/api/{service}/{action}
```
**Examples:**
```
/api/llm/generate
/api/maps/render
/api/rag/query
```
***
#### **5.3 Job Abstraction**
```
Job {
id
type
payload
status
result
}
```
***
### **6. Scaling Model**
#### **6.1 Vertical Scaling**
* Increase CPU / RAM
* Especially important for LLM workloads
#### **6.2 Horizontal Scaling (Future)**
* Multi-node architecture
* Distributed querying
* Node-to-node synchronization
***
### **7. Security Model (Implicit)**
* Local-first access
* No external exposure by default
* Optional authentication layer
* Air-gap compatible
***
### **8. Mental Model (Simplified)**
Think of an EPIZO Node as:
> **“An Offline Cloud in a Box”**
Inside a single machine, you have:
* AI (LLM)
* Wikipedia (ZIM)
* Maps
* Database
* Queue system
* Web UI
***
### **9. Advanced Evolution (Next Steps)**
#### **1. Mesh Networking**
* Node-to-node synchronization
* Distributed knowledge sharing
#### **2. Service Discovery**
* Automatic service detection
* Dynamic routing
#### **3. WASM Plugin System**
* Sandboxed execution
* Extensible ecosystem
#### **4. Data Federation Layer**
* Query multiple nodes as a single system
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.projectepizo.com/epizo-node.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.