Implexus/Architecture/10-File-Organization.md

File Organization

This document maps out the source files to create for the Implexus project.

Project Structure

implexus/
├── meson.build                    # Main build configuration
├── MANIFEST.usm                   # USM package manifest
├── README.md                      # Project readme
├── LICENSE                        # License file
│
├── src/                           # Source files
│   ├── meson.build               # Source build configuration
│   │
│   ├── core/                     # Implexus.Core namespace
│   │   ├── entity.vala           # Entity interface
│   │   ├── entity-type.vala      # EntityType enum
│   │   ├── engine.vala           # Engine interface
│   │   ├── path.vala             # Path class
│   │   ├── transaction.vala      # Transaction interface
│   │   ├── errors.vala           # EngineError domain
│   │   ├── embedded-engine.vala  # EmbeddedEngine implementation
│   │   └── remote-engine.vala    # RemoteEngine implementation
│   │
│   ├── entities/                 # Implexus.Entities namespace
│   │   ├── abstract-entity.vala  # AbstractEntity base class
│   │   ├── container.vala         # Container entity
│   │   ├── document.vala         # Document entity
│   │   ├── category.vala        # Category entity
│   │   ├── category-container.vala # Virtual container from category
│   │   ├── index.vala            # Index entity
│   │   ├── index-result.vala     # IndexResult entity
│   │   └── entity-set.vala       # EntitySet for set operations
│   │
│   ├── storage/                  # Implexus.Storage namespace
│   │   ├── storage.vala          # Storage interface
│   │   ├── dbm.vala              # DBM interface
│   │   ├── filesystem-dbm.vala   # FilesystemDbm implementation
│   │   ├── default-storage.vala  # DefaultStorage implementation
│   │   ├── storage-configuration.vala # Configuration class
│   │   └── errors.vala           # StorageError domain
│   │
│   ├── serialization/            # Implexus.Serialization namespace
│   │   ├── element-writer.vala   # ElementWriter class
│   │   ├── element-reader.vala   # ElementReader class
│   │   ├── entity-serializer.vala # EntitySerializer class
│   │   ├── entity-deserializer.vala # EntityDeserializer class
│   │   ├── errors.vala           # SerializationError domain
│   │   └── format.vala           # Format constants
│   │
│   ├── protocol/                 # Implexus.Protocol namespace
│   │   ├── message.vala          # Message interface and header
│   │   ├── request.vala          # Request interface
│   │   ├── response.vala         # Response interface
│   │   ├── message-reader.vala   # MessageReader class
│   │   ├── message-writer.vala   # MessageWriter class
│   │   ├── requests.vala         # All request classes
│   │   ├── responses.vala        # All response classes
│   │   └── errors.vala           # ProtocolError domain
│   │
│   └── server/                   # Implexus.Server namespace
│       ├── server.vala           # Server class
│       ├── client-connection.vala # ClientConnection class
│       ├── request-handler.vala  # RequestHandler class
│       ├── server-configuration.vala # ServerConfiguration class
│       └── errors.vala           # ServerError domain
│
├── vapi/                         # VAPI files
│   ├── implexus.deps             # Dependencies file
│   └── implexus.vapi             # Generated VAPI
│
├── examples/                     # Example programs
│   ├── meson.build
│   ├── basic-usage.vala          # Basic usage example
│   ├── category-example.vala    # Category usage
│   ├── index-example.vala        # Index usage
│   ├── set-operations.vala       # Set operations example
│   └── remote-client.vala        # Remote client example
│
├── tools/                        # Command-line tools
│   ├── meson.build
│   ├── implexusd.vala            # Server daemon
│   └── implexus-cli.vala         # Command-line client
│
└── tests/                        # Test suite
    ├── meson.build
    ├── test-path.vala            # Path tests
    ├── test-entity.vala          # Entity tests
    ├── test-storage.vala         # Storage tests
    ├── test-serialization.vala   # Serialization tests
    ├── test-protocol.vala        # Protocol tests
    └── test-integration.vala     # Integration tests

File Details

Core Files

File	Namespace	Purpose
entity.vala	Implexus.Core	Entity interface definition
entity-type.vala	Implexus.Core	EntityType enum
engine.vala	Implexus.Core	Engine interface
path.vala	Implexus.Core	Path parsing and manipulation
transaction.vala	Implexus.Core	Transaction interface
errors.vala	Implexus.Core	EngineError errordomain
embedded-engine.vala	Implexus.Core	EmbeddedEngine class
remote-engine.vala	Implexus.Core	RemoteEngine class

Entity Files

File	Namespace	Purpose
abstract-entity.vala	Implexus.Entities	AbstractEntity base class
container.vala	Implexus.Entities	Container entity
document.vala	Implexus.Entities	Document entity
category.vala	Implexus.Entities	Category entity
category-container.vala	Implexus.Entities	Virtual container from category
index.vala	Implexus.Entities	Index entity
index-result.vala	Implexus.Entities	IndexResult entity
entity-set.vala	Implexus.Entities	EntitySet for set operations

Storage Files

File	Namespace	Purpose
storage.vala	Implexus.Storage	Storage interface
dbm.vala	Implexus.Storage	DBM interface
filesystem-dbm.vala	Implexus.Storage	FilesystemDbm file-based implementation
default-storage.vala	Implexus.Storage	DefaultStorage implementation
storage-configuration.vala	Implexus.Storage	Configuration class
errors.vala	Implexus.Storage	StorageError errordomain

Serialization Files

File	Namespace	Purpose
element-writer.vala	Implexus.Serialization	ElementWriter class
element-reader.vala	Implexus.Serialization	ElementReader class
entity-serializer.vala	Implexus.Serialization	EntitySerializer class
entity-deserializer.vala	Implexus.Serialization	EntityDeserializer class
errors.vala	Implexus.Serialization	SerializationError errordomain
format.vala	Implexus.Serialization	Format constants

Protocol Files

File	Namespace	Purpose
message.vala	Implexus.Protocol	Message interface and header
request.vala	Implexus.Protocol	Request interface
response.vala	Implexus.Protocol	Response interface
message-reader.vala	Implexus.Protocol	MessageReader class
message-writer.vala	Implexus.Protocol	MessageWriter class
requests.vala	Implexus.Protocol	All request classes
responses.vala	Implexus.Protocol	All response classes
errors.vala	Implexus.Protocol	ProtocolError errordomain

Server Files

File	Namespace	Purpose
server.vala	Implexus.Server	Server class
client-connection.vala	Implexus.Server	ClientConnection class
request-handler.vala	Implexus.Server	RequestHandler class
server-configuration.vala	Implexus.Server	ServerConfiguration class
errors.vala	Implexus.Server	ServerError errordomain

Build Configuration

Root meson.build

project('implexus', 'vala', 'c',
    version: '0.1.0',
    meson_version: '>= 0.50.0'
)

gnome = import('gnome')

glib_dep = dependency('glib-2.0')
gobject_dep = dependency('gobject-2.0')
invercargill_dep = dependency('invercargill-1')

dependencies = [
    glib_dep,
    gobject_dep,
    invercargill_dep
]

subdir('src')
subdir('examples')
subdir('tools')
subdir('tests')

src/meson.build

lib_sources = files(
    'core/entity.vala',
    'core/entity-type.vala',
    'core/engine.vala',
    'core/path.vala',
    'core/transaction.vala',
    'core/errors.vala',
    'core/embedded-engine.vala',
    'core/remote-engine.vala',
    'entities/abstract-entity.vala',
    'entities/container.vala',
    'entities/document.vala',
    'entities/category.vala',
    'entities/category-container.vala',
    'entities/index.vala',
    'entities/index-result.vala',
    'entities/entity-set.vala',
    'storage/storage.vala',
    'storage/dbm.vala',
    'storage/filesystem-dbm.vala',
    'storage/default-storage.vala',
    'storage/storage-configuration.vala',
    'storage/errors.vala',
    'serialization/element-writer.vala',
    'serialization/element-reader.vala',
    'serialization/entity-serializer.vala',
    'serialization/entity-deserializer.vala',
    'serialization/errors.vala',
    'serialization/format.vala',
    'protocol/message.vala',
    'protocol/request.vala',
    'protocol/response.vala',
    'protocol/message-reader.vala',
    'protocol/message-writer.vala',
    'protocol/requests.vala',
    'protocol/responses.vala',
    'protocol/errors.vala',
    'server/server.vala',
    'server/client-connection.vala',
    'server/request-handler.vala',
    'server/server-configuration.vala',
    'server/errors.vala'
)

implexus_lib = library('implexus',
    lib_sources,
    dependencies: dependencies,
    version: '0.1.0',
    install: true
)

implexus_dep = declare_dependency(
    link_with: implexus_lib,
    dependencies: dependencies
)

install_data('vapi/implexus.deps', install_dir: get_option('datadir') / 'vala/vapi')

gnome.generate_vapi('implexus',
    sources: lib_sources,
    packages: ['glib-2.0', 'gobject-2.0', 'invercargill-1'],
    install: true
)

Dependencies File

vapi/implexus.deps

glib-2.0
gobject-2.0
invercargill-1

Example Files

examples/basic-usage.vala

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

public int main(string[] args) {
    // Create storage
    var dbm = new FilesystemDbm("/tmp/implexus-demo");
    var storage = new DefaultStorage(dbm);
    storage.open();
    
    // Create embedded engine
    var engine = new EmbeddedEngine(storage);
    
    // Create a container hierarchy
    var root = engine.get_root();
    var users = root.create_container("users");
    
    // Create a document
    var john = users.create_document("john", "User");
    john.set_property("email", new Invercargill.ValueElement("john@example.com"));
    john.set_property("age", new Invercargill.ValueElement(30));
    
    // Read it back
    var loaded = engine.get_entity(new Path("/users/john")) as Document;
    print("Email: %s\n", loaded.get_property("email").to_string());
    print("Age: %s\n", loaded.get_property("age").to_string());
    
    // Clean up
    storage.close();
    return 0;
}

Tool Files

tools/implexusd.vala

using Implexus.Core;
using Implexus.Server;
using Implexus.Storage;

public int main(string[] args) {
    string data_dir = "/var/lib/implexus";
    uint16 port = 9090;
    
    // Parse arguments
    for (int i = 1; i < args.length; i++) {
        if (args[i] == "--port" && i + 1 < args.length) {
            port = (uint16) int.parse(args[++i]);
        } else if (args[i] == "--data-dir" && i + 1 < args.length) {
            data_dir = args[++i];
        }
    }
    
    // Initialize storage
    var dbm = new FilesystemDbm(data_dir);
    var storage = new DefaultStorage(dbm);
    
    try {
        storage.open();
    } catch (StorageError e) {
        stderr.printf("Failed to open storage: %s\n", e.message);
        return 1;
    }
    
    // Create engine and server
    var engine = new EmbeddedEngine(storage);
    var config = new ServerConfiguration();
    config.port = port;
    
    var server = new Server(engine, config.port);
    
    try {
        server.start();
        print("Implexus server started on port %u\n", port);
        
        // Wait for termination
        var loop = new MainLoop();
        loop.run();
        
    } catch (ServerError e) {
        stderr.printf("Server error: %s\n", e.message);
        return 1;
    }
    
    storage.close();
    return 0;
}

Test Files

tests/test-path.vala

using Implexus.Core;

public class PathTests : Object {
    
    public void test_root_path() {
        var root = new Path.root();
        assert(root.is_root);
        assert(root.depth == 0);
        assert(root.to_string() == "/");
    }
    
    public void test_simple_path() {
        var path = new Path("/users/john");
        assert(!path.is_root);
        assert(path.depth == 2);
        assert(path.name == "john");
        assert(path.parent.name == "users");
    }
    
    public void test_child_operations() {
        var parent = new Path("/users");
        var child = parent.child("john");
        
        assert(child.depth == 2);
        assert(child.is_descendant_of(parent));
        assert(parent.is_ancestor_of(child));
    }
    
    public void test_equality() {
        var a = new Path("/users/john");
        var b = new Path("/users/john");
        var c = new Path("/users/jane");
        
        assert(a.equals(b));
        assert(!a.equals(c));
    }
    
    public void test_resolution() {
        var base = new Path("/users");
        var resolved = base.resolve(new Path("john/profile"));
        
        assert(resolved.to_string() == "/users/john/profile");
    }
    
    public static int main(string[] args) {
        var tests = new PathTests();
        
        tests.test_root_path();
        tests.test_simple_path();
        tests.test_child_operations();
        tests.test_equality();
        tests.test_resolution();
        
        print("All path tests passed!\n");
        return 0;
    }
}

File Creation Order

When implementing, create files in this order:

1. Core Interfaces - entity.vala, entity-type.vala, engine.vala, errors.vala
2. Path System - path.vala
3. Storage Layer - storage.vala, dbm.vala, basic-dbm.vala, default-storage.vala
4. Serialization - format.vala, element-writer.vala, element-reader.vala, entity-serializer.vala, entity-deserializer.vala
5. Entity Base - abstract-entity.vala
6. Entity Types - container.vala, document.vala, category.vala, index.vala
7. Set Operations - entity-set.vala
8. Engine Implementations - embedded-engine.vala, transaction.vala
9. Protocol - message.vala, request.vala, response.vala, message reader/writer, request/response classes
10. Remote Engine - remote-engine.vala
11. Server - server.vala, client-connection.vala, request-handler.vala
12. Tools - implexusd.vala, implexus-cli.vala
13. Examples - All example files
14. Tests - All test files