Implexus/Architecture/02-Namespaces.md

Namespace Organization

Namespace Hierarchy

Implexus uses a hierarchical namespace structure following Vala conventions:

Implexus                          // Root namespace
├── Core                          // Core interfaces and types
├── Entities                      // Entity implementations
├── Storage                       // Storage layer
├── Serialization                 // Binary serialization
├── Protocol                      // Client/server protocol
└── Server                        // Daemon implementation

Namespace Details

Implexus.Core

Core interfaces and enums that define the public API.

Type	Kind	Description
Entity	interface	Base interface for all database entities
EntityType	enum	CONTAINER, DOCUMENT, CATEGORY, INDEX
Engine	interface	Unified API for embedded and remote modes
Path	class	Path parsing and manipulation
EntityReference	class	Reference to an entity by path
EngineError	errordomain	Engine operation errors

Implexus.Entities

Concrete entity implementations.

Type	Kind	Description
AbstractEntity	abstract class	Base implementation with common functionality
Container	class	Container entity for child entities
Document	class	Properties-based document entity
Category	class	Expression-based auto-categorization
Index	class	Text search with dynamic categories
IndexResult	class	Container returned by index queries
EntitySet	class	Set operations over entity collections

Implexus.Storage

Storage abstraction layer.

Type	Kind	Description
Storage	interface	Entity persistence operations
DBM	interface	DBM-style key-value storage
FilesystemDbm	class	Filesystem-based DBM implementation
StorageConfiguration	class	Storage configuration options
Transaction	interface	Transaction support for writes

Implexus.Serialization

Binary serialization for Element types.

Type	Kind	Description
ElementWriter	class	Writes Element values to binary
ElementReader	class	Reads Element values from binary
EntitySerializer	class	Serializes entities to binary
EntityDeserializer	class	Deserializes entities from binary
SerializationFormat	enum	Format version identifiers

Implexus.Protocol

Client/server communication protocol.

Type	Kind	Description
Message	interface	Base protocol message
Request	interface	Client request message
Response	interface	Server response message
MessageReader	class	Reads messages from stream
MessageWriter	class	Writes messages to stream
ProtocolError	errordomain	Protocol-level errors

Implexus.Server

Daemon implementation for client/server mode.

Type	Kind	Description
Server	class	Main daemon server
ClientConnection	class	Handles individual client
RequestHandler	class	Processes client requests
ServerConfiguration	class	Server configuration options

Namespace Dependencies

graph TD
    A[Implexus.Core] --> B[Invercargill]
    C[Implexus.Entities] --> A
    C[Implexus.Entities] --> D[Implexus.Serialization]
    D[Implexus.Serialization] --> B
    E[Implexus.Storage] --> A
    E[Implexus.Storage] --> D
    F[Implexus.Protocol] --> A
    F[Implexus.Protocol] --> D
    G[Implexus.Server] --> E
    G[Implexus.Server] --> F
    G[Implexus.Server] --> C

External Dependencies

Dependency	Usage
GLib-2.0	Basic types, error domains
GObject-2.0	Object system
Invercargill-1	Element, Properties, Enumerable, Lot, Set, Expressions, DataStructures

Naming Conventions

Interfaces

• PascalCase names
• No I prefix (Vala convention)
• Examples: Entity, Engine, Storage, DBM

Classes

• PascalCase names
• Abstract classes prefixed with Abstract
• Examples: Container, Document, AbstractEntity

Enums

• PascalCase for type name
• UPPER_SNAKE_CASE for values
• Examples: EntityType.CONTAINER, EntityType.DOCUMENT

Error Domains

• PascalCase with Error suffix
• UPPER_SNAKE_CASE for codes
• Examples: EngineError.ENTITY_NOT_FOUND

Delegates

• PascalCase with descriptive suffix
• Examples: EntityFilter, EntityTransform

Usage Example

using Implexus.Core;
using Implexus.Entities;
using Implexus.Storage;

public int main(string[] args) {
    // Create storage
    var dbm = new FilesystemDbm("/path/to/database");
    var storage = new DefaultStorage(dbm);
    
    // Create embedded engine
    var engine = new EmbeddedEngine(storage);
    
    // Work with entities
    var root = engine.get_root();
    var users = root.create_container("users");
    var doc = users.create_document("john", "UserProfile");
    doc.set_property("email", new ValueElement("john@example.com"));
    
    return 0;
}