Platform Structure Guide

This guide defines the canonical locations, names, and roles of Elonn platform artifacts.

Component Repositories

Each Component has its own repository and domain.

Development repositories use:

domains/<component>.elonn.local/

Production uses the corresponding:

<component>.elonn.com

The domain identifies the Component. It does not imply that the Component exposes a public member-facing interface.

A Component repository contains:

domains/<component>.elonn.local/
├── <COMPONENT>.md
└── README.md

A Component that is a Service additionally contains:

domains/<service>.elonn.local/
├── <SERVICE>.md
├── README.md
└── public/
    ├── <service>.md
    ├── <service>.json
    └── <service>-publication.json

For example:

domains/maps.elonn.local/
├── MAPS.md
├── README.md
└── public/
    ├── maps.md
    ├── maps.json
    └── maps-publication.json

Additional implementation files and directories may exist as required.

Repository and Published Locations

Repository locations and published URLs are distinct.

Service publication artifacts maintained at:

public/<service>.md
public/<service>.json
public/<service>-publication.json

is published at:

https://<service>.elonn.com/<service>.md
https://<service>.elonn.com/<service>.json
https://<service>.elonn.com/<service>-publication.json

The repository's public/ directory is the document root and therefore does not appear in the published URL.

Platform Architecture

ELONN.md defines the Elonn platform architecture.

It defines Components, roles, boundaries, relationships, communication rules, and platform invariants.

Component Specification

<COMPONENT>.md

The Component specification defines the Component: its purpose, responsibilities, boundaries, relationships, and architectural requirements.

Examples:

WORLD.md
MIND.md
MAPS.md
FIND.md

Repository README

README.md

The README describes the repository and its implementation, including development, configuration, operation, testing, and deployment.

It references rather than replaces the Component specification and other authoritative artifacts.

Service Contract

Each Service publishes one Service contract in two forms:

public/<service>.json
public/<service>.md

The JSON contract is normative.

The Markdown contract is its human-readable description.

Service contracts are governed by the Contract Authoring Guide.

Service Publication

Each Service publishes one Service Publication:

public/<service>-publication.json

The Service Publication identifies the Service, describes selectable capabilities, and locates the authoritative Service contract.

The Service Publication is the authority for deciding whether to consider a Service.

The Service Publication is indexed by Conductor's Service Registry.

The Service Publication is not a Dataset and does not duplicate the Service contract.

Canonical Structures

Platform-wide shared structures are published under:

dev.elonn.com/public/canonical/

Each canonical structure has:

<structure>.json
<structure>.md

The JSON definition is normative.

The Markdown document is its human-readable description.

Canonical structures are governed by the Canonical Structure Policy.

Governance

Platform-wide rules and guidance are maintained under:

dev.elonn.com/public/

The primary governance documents are:

platform-structure-guide.md
canonical-structure-policy.md
contract-authoring-guide.md
admin-observability-guide.md

platform-structure-guide.md defines where platform artifacts belong.

canonical-structure-policy.md defines the requirements for canonical structures.

contract-authoring-guide.md defines how Service contracts are authored.

Authority

Each artifact has one role:

ELONN.md

<COMPONENT>.md
Component specification

README.md
Repository and implementation documentation

public/<service>.json
Normative Service contract

public/<service>.md
Human-readable Service contract

public/<service>-publication.json
Service Publication indexed by Service Registry

canonical/<structure>.json
Normative canonical structure

canonical/<structure>.md
Human-readable canonical structure

Governance documents
Platform-wide rules and guidance
```

An artifact may reference or summarize another artifact but does not redefine it.

Duplication does not create authority.