# 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

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

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

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

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

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