# 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

```mermaid
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

```vala
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;
}
```