← Heliacon

Origin architecture

This document describes how Heliacon is built. It is the technical companion to the manifesto. The manifesto says why. This says how. It is also the reference for the architecture we bring to client work: any organisation can be origin-first by the same construction.

The one idea

There is a single canonical source. Every representation is generated from it and traces back to it. Nothing authoritative exists that is not a projection of the origin.

origin (source of truth)  ->  projections (html, json, jsonld, markdown, llms.txt, mcp)

The origin is not a website with an API bolted on. The website is a projection, equal in standing to the JSON and the MCP tools. The browser is not privileged. Neither is the agent.

The origin

The origin is structured data plus a corpus, not prose.

  • origin.yaml is the canonical identity: id, name, tagline, description, principles, capabilities, and the list of projections. It is authored first. origin.md is generated from it, not the other way round.
  • corpus/ holds the body of work. Each entry is a versioned document with an id, a title, a status, an author, an updated date, and its relationships to other entries.
  • definitions/ holds the canonical terms, each conforming to schemas/definition.schema.json.

Structured first means every projection is consistent by construction, because they are all rendered from the same object.

Projections

A projection is a representation of the origin, negotiated for a given consumer. The build renders all of them from source in one pass:

  • HTML for browsers.
  • JSON and JSON-LD for agents and crawlers.
  • Markdown for writers and for models that prefer it.
  • llms.txt as a clean index for language models.
  • MCP so an agent can call the origin as tools.

Projections are deterministic. The same source produces the same output every time. Adding a new projection is adding a new renderer, never a new source of truth.

Negotiation

One URL serves many representations. An edge worker reads the Accept header and returns the representation the caller asked for. A browser asking for text/html and an agent asking for application/json hit the same address and each gets what it can use. This is where "the browser is not privileged" stops being a slogan and becomes code.

Provenance

Every projection carries its lineage. A claim is not just from Heliacon, it is from this entry, at this version, updated on this date, with a link back to its source. /provenance returns the record for any item. Versioning is part of provenance: an origin evolves like software, so a reader can pin what they cite.

Capabilities

An origin is judged by what it can do. The capabilities are invocable at stable URLs and over MCP, not merely described:

  • ask retrieves the passages of the corpus that answer a question, each with its citation. No answer is generated at the origin. The caller synthesises from cited source.
  • definitions returns a canonical definition as data.
  • provenance returns the source and version of any item.

The MCP server at /mcp exposes these as tools. It is read-only over its own data, so it can be consumed but not abused.

Discovery

The origin advertises itself: sitemap.xml, robots.txt, llms.txt, an Atom feed, and a manifest at /.well-known/mcp.json that lists the live capabilities and their endpoints. The manifest describes only what actually resolves. It does not advertise capability that does not exist.

Build and deploy

The whole origin is one language, TypeScript, so the generator and the edge code share a runtime. build.ts renders dist/ from source. The same audit and content code runs locally and on the edge. Deployment is a Cloudflare Worker with static assets, redeployed on every push to main. dist/ is never committed. It is a projection, and projections are rebuilt, never stored.

Discipline

Every change answers one question. Does this make the origin more canonical. Not, does this make the website prettier. The repository is the architecture. If the repository needs a framework to explain itself, the architecture is wrong.

Status

This repository is the reference implementation. The architecture may in time be published as an open specification, so that others can implement it while Heliacon remains the canonical origin and the reference build. The name is the moat, not the mechanism.