This blog is not yet powered by SERVPHER. The article you are currently reading is still processed by Jekyll, being transformed into a static website and presented using the So Simple theme. For many years, this setup has served METACODES.PRO reliably. Nevertheless, maintaining the machinery around the articles has gradually become more cumbersome (for me) than maintaining the articles themselves.
Ruby versions have to match and Gems need compatible versions. Themes evolve or cease to evolve. SASS depreciations appear and make migrations necessary. Plugins add dependencies and may break thinks (for me). A seemingly harmless update can turn into an afternoon spent investigating why the website no longer builds or why the generated result suddenly looks different. None of this makes Jekyll a bad tool:
Moreover, it solved an important problem elegantly: Markdown documents can be transformed into a fast and portable website requiring no application server. However, my own requirements have gradually moved in another direction. I want the content to remain accessible as information rather than disappear into a build artifact and I want to inspect it, enrich it, query it and represent it differently for different consumers. I want static documents and dynamically generated information to participate in the same model. Most importantly though: I want the architecture surrounding my content to remain under my control.
The first idea was deceptively small:
What if I simply expose a directory containing Markdown documents through HTTP?
This idea became SERVPHER. The project is still under active development, its user interface is not finished, several capabilities required for replacing METACODES.PRO are still missing and much of the current Single Page Application (SPA) is intended for architectural exploration rather than for readers of a finished website. However, SERVPHER is beginning to take shape and more importantly, it does no longer feel like an experimental file server. A coherent architecture has emerged - one that may eventually allow METACODES.PRO to leave its (please bear with me) increasingly cumbersome Jekyll machinery behind.
SERVPHER is not finished, but its architectural identity is becoming visible.
Gopher as a source of inspiration
Long before today’s web applications accumulated client-side frameworks, build pipelines, package managers and layers of content transformation, the Gopher protocol offered a remarkably simple way of navigating information on the Internet. A Gopher client requested a selector from a server and the server responded either with a resource or with a menu containing references to further resources. These menus formed what appeared to the user as a virtual hierarchical filesystem. Conceptually, a Gopherspace resembled something like this:
ROOT
│
├── Documentation
│ ├── Introduction
│ ├── Installation
│ └── Configuration
│
├── Articles
│ ├── Computing
│ ├── Software architecture
│ └── Computer archaeology
│
└── Downloads
├── Source code
└── Documents
This model was deliberately modest: A resource could be a document, a submenu, a search service or any other supported type of information. Navigation emerged naturally from menus returned by servers and clients did not need to understand the internal storage structure behind those menus, nor did servers prescribe a complex presentation layer. Gopher was eventually overshadowed by the World Wide Web (WWW), whose hypertext model and visual possibilities offered a high degree of flexibility. Though I do not intend to recreate Gopher, nor is SERVPHER an implementation of the Gopher protocol!
Still several of Gopher’s ideas remained fascinating to me and inspired me:
- Information is organized into navigable structures
- Resources are identified independently of their presentation
- A server exposes information rather than application screens
- Clients remain consumers of a shared information space
- A hierarchy can provide useful navigation without requiring a backed content model
- Simple resources can form surprisingly expressive systems
The inspiration is of a conceptual nature rather than being protocol-specific. Gopher begins with a hierarchy of resources and SERVPHER begins with a graph of information. Gopher menus describe where a user may continue navigating and SERVPHER nodes describe information, relationships, metadata and optional content. Gopher clients interpret resource types and SERVPHER clients request projections of the same underlying information. One might describe SERVPHER as an exploration of what some of Gopher’s simplicity could look like when combined with modern content negotiation, semantic metadata, dynamic information and transport-independent representations.
Gopher ─▸ Hierarchical resources ─▸ Navigable information space ─▸ SERVPHER ─▸ Semantic node graph ─▸ Multiple projections and clients
Gopher provided the inspiration to think of a server as an entrance into an information space rather than as a collection of application endpoints.
The motivation behind SERVPHER
The content of METACODES.PRO is already stored in a mostly generic form: Articles are Markdown documents and images as well as other resources are files. Metadata such as titles, publication dates, categories and tags accompany the content, directories provide a degree of organization. Why should publishing such information require reconstructing an entire website? Why must a document first be transformed into generated files before a web server can expose it? Why should navigation, metadata, content and presentation become intertwined with a particular generator, a templating system and a theme? A static site generator answers these questions by producing the final website ahead of time: The generated result is simple to deploy and efficient to serve. My requirements increasingly point toward an information system that remains alive at runtime (but still my produce static ahead of time presentations).
I want to be able to:
- Inspect the available information
- Request different representations
- Enrich documents through processors
- Add virtual or generated content
- Develop a user interface independently of the content model
- Introduce new information sources without rewriting the presentation
- Preserve the original markdown documents as portable content
The immediate objective is practical:
SERVPHER is intended eventually to replace the Jekyll driven METACODES.PRO website.
A broader architectural objective emerged while working toward it:
Content should be modeled independently of storage, representation, transport and presentation.
The first objective gives SERVPHER a genuine application and a measurable destination and the second prevents it from degenerating into a collection of shortcuts tailored exclusively to my current blog.
Beginning with files
The first versions of SERVPHER were (intentionally) centered around files. Given a directory such as:
content/
├── index.md
├── about.md
├── blog/
│ ├── first-article.md
│ └── second-article.md
└── assets/
├── style.css
└── logo.png
… the server should discover its resources and expose them through HTTP. This already eliminates a surprising amount of application code. No controller needs to be implemented for each document and no Data Transfer Objects (DTO) have to reproduce the directory structure as well as no route table needs to be synchronized manually with the available articles.
The filesystem inherently already contains relevant information:
Directories establish a hierarchy- Filenames identify resources
- File extensions suggest media types
- An
index.md document naturally represents its surrounding Directory
- Numeric prefixes define ordering
- Dot
. prefixed names identify hidden resources
It initially seemed reasonable to make this filesystem hierarchy the central model though that assumption did not survive for long. Classpath resources had to participate as well, particularly the JavaScript, Cascading Style Sheets (CSS) and HyperText Markup Language (HTML) resources belonging to the bundled SPA. Directories obtained their own content through therein contained Index resources. Metadata began to originate from filenames, Markdown front matter and Sidecar documents. Dynamically generated information was supposed to behave like stored information. The filesystem remained important, but it was no longer sufficient as the domain model: A more general abstraction was required.
From files to nodes
The central abstraction that emerged is the Node, it represents an identifiable piece of information. It is deliberately not defined as a file, directory, web page or REST resource, moreover depending upon its origin and purpose, a Node may represent:
- A filesystem resource
- A directory
- A classpath resource
- A markdown document
- An image
- Generated content
- A virtual resource
- A remote information source
- A capability capable of producing information
Every Node participates in the same domain model and may expose:
- Identity
- Logical location
- Name
- Metadata
- Relationships
- Optional content
The content is optional because not every Node needs to contain readable bytes. A Directory may primarily organize other Nodes, a virtual Node may describe a capability or a dynamically handled Node may produce content only when it is invoked.
A Node represents information rather than the mechanism storing that information.
This distinction allows the architecture to model what information means without coupling that meaning to the mechanism currently providing it. A Markdown document, a generated report and an image loaded from remote storage may originate from completely different technologies. Once they have entered the Node Graph, however, they participate in identical navigation, metadata, querying and projection semantics.
The node graph as the single source of truth
Nodes do not exist in isolation as together they form the Node Graph which represents the canonical information model of SERVPHER.
The graph establishes relationships such as:
- Parent
- Children
- Siblings
- Previous
- Next
- Root
- Breadcrumb
- Self
Navigation therefore does not have to be recreated independently for each representation: Navigation emerges from the relationships already contained within the graph.
ROOT
│
├── Documentation
│ ├── Introduction
│ ├── Installation
│ └── Configuration
│
├── Assets
│ ├── Stylesheets
│ ├── JavaScript
│ └── Images
│
└── Blog
├── Article 1
└── Article 2
This resembles the hierarchical navigation that made Gopher so approachable, but the SERVPHER model deliberately extends beyond a tree of menu entries. Nodes can expose rich Metadata, relationships can become more semantic or queries may select particular views, moreover different Projections can represent the same Node differently. Dynamic and virtual Nodes can participate without pretending or simulating to be stored files. The graph also abstracts away the physical origins of its Nodes as one subtree may have been discovered from the filesystem and another subtree from the application classpath and yet a third subtree may consist entirely of dynamically produced Nodes. A client navigating the graph does not need to know these implementation details: This provides one canonical model from which every representation can be derived.
Node Grap
│
┌────────┼────────┐
│ │ │
▼ ▼ ▼
JSON Markdown Binary
│ │ │
└────────┼────────┘
│
Future projections
Without a canonical graph, different outputs tend to develop independent interpretations of the same content. A browser may construct one navigation model, a REST interface another and a future command-line application yet another. This leads to visibility, ordering and Metadata gradually becoming inconsistent. By establishing the Node Graph as the single source of truth, SERVPHER attempts to prevent this duplication.
Information is modeled once and represented many times.
The filesystem as a declarative language
Although the filesystem is no longer the domain model, it remains a convenient way of constructing parts of the graph. During development, several lightweight filename semantics have emerged.
An ordered collection can be expressed as follows:
10--Introduction.md
20--Installation.md
30--Configuration.md
The numeric prefixes become ordering Metadata, while the logical Node names remain:
Introduction.md
Installation.md
Configuration.md
A leading dot marks a Node as hidden:
A Bookmark identifier can provide a stable reference independent of the Node’s current location:
Installation [INSTALL].md
An Index resource turns its surrounding Directory into a content-bearing Node:
documentation/
├── index.md
├── introduction.md
└── installation.md
Clients may then address /documentation without knowing that the Directory obtains its content from index.md.
Additional Metadata may accompany an article using a Sidecar document:
article.md
article.md.yml
Markdown front matter provides another source:
---
title: Exploring SERVPHER
category: Software Architecture
tags:
- SERVPHER
- Java
---
# Exploring SERVPHER
Individually, these conventions are small conveniences though together they turn the filesystem into a lightweight Domain-Specific Language (DSL) describing an information graph.
20--Documentation [DOC]/
├── index.md
├── 10--Introduction.md
├── 20--Installation.md
└── .draft.md
Without opening a single document, SERVPHER can already derive:
- The
Node hierarchy
- The navigation order
- A stable
Bookmark
- The
Directory’s Index content
- The hidden state of the draft
The filesystem is not merely storage as it is one possible declarative language for constructing the Node Graph.
This is particularly attractive for the eventual migration of METACODES.PRO because the articles should remain ordinary, portable documents rather than records trapped within an application-specific database.
As more semantics were introduced, another architectural separation became necessary: Discovering information is not the same as understanding it, therefore SERVPHER distinguishes between Scanners and Processors.
A Scanner discovers Nodes:
Filesystem ──► Filesystem Scanner ──┐
│
Classpath ──► Classpath Scanner ───┼──► Node Graph
│
Future Source ─► Future Scanner ────┘
A Processor enriches Nodes that have already been discovered. Processors may extract Markdown Metadata, merge Sidecar Metadata, resolve placeholders or derive future semantic relationships.
Initial Node Graph ─▸ Sidecar Processor ─▸ Markdown Processor ─▸ Future Processors ─▸ Enriched Node Graph
This distinction keeps Scanners focused. A filesystem Scanner should discover that a Markdown document exists, establish its position in the graph and attach immediately available structural Metadata. It should not simultaneously become a Markdown parser, taxonomy generator, search indexer and publication workflow. Each Processor contributes one additional aspect of understanding.
Scanners discover information, Processors progressively understand it.
The processing model has started to become one of the strongest aspects of SERVPHER. New behavior can be introduced as another stage in the pipeline rather than by continuously enlarging one central component.
Projection is not serialization
Exposing the graph through HTTP initially suggested an obvious implementation: Serialize the Nodes as JSON:
This works-until it does not!
Serialization converts an object structure into another format. It commonly exposes the structure of an implementation rather than deliberately describing the information required by a particular client. One client may require only a single Node and another one may need its immediate children. A debugging client may request Metadata, relationships and embedded content and a browser may prefer Markdown, HTML or an image. Hidden Nodes may need to be excluded or large subtrees may have to remain collapsed. These are not merely serialization concerns. They are Projection concerns. A Projection creates a particular view of the Node Graph.
A client expresses its intended observation through a ProjectionQuery, including concepts such as:
- Depth
- Visibility
- Included fields
- Excluded fields
- Accepted media types
The graph itself remains unchanged.
Node Graph
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
application/ Markdown Binary
servpher+json projection pass-through
Two Projections may differ substantially while still describing the same underlying Node.
Serialization exposes an object, Projection creates a view of information.
The result of a Projection is a transport-independent ProjectionRepresentation. It encapsulates the media type, content stream and optional content length, but it does not own HTTP status codes, response headers or Spring specific response objects. A transport adapter determines how the representation is delivered. This may appear elaborate for serving a blog article, but it protects the content model from the technology currently carrying it. Today, that transport is primarily HTTP but the architecture should not depend upon this remaining true forever.
Static and dynamic content become equal
Traditional web architectures often treat static and dynamic content through completely different mechanisms: A web server delivers files and (REST-)Controllers generate responses and templates render pages. Each mechanism may have its own routing, metadata and error handling - SERVPHER attempts to avoid this division.
SERVPHER distinguishes only between:
- Information that already exists
- Information that can be produced
Handlers contribute behavior to Nodes and may generate content upon invocation. The Node continues to own its identity, relationships and Metadata, while the Handler provides runtime behavior. From the perspective of Projection, the resulting content remains an ordinary stream. This permits Nodes with no corresponding physical resource.
A future graph might contain Nodes such as:
/system/status
/reports/monthly
/database/statistics
/search/results
These Nodes are not simulated files., moreover they are virtual information bearing elements within the same graph. This capability is not yet central to replacing METACODES.PRO, but it demonstrates that the emerging architecture is no longer constrained to reproducing a static website.
Dynamic content is not a special extension of the model, it is a natural consequence of modeling information independently of storage.
The SPA as an architectural test
SERVPHER currently includes a bundled Single Page Application (SPA). It primarily serves as a debugging and exploration interface by visualizing Nodes, Metadata, links, child relationships and embedded content. Binary content embedded within the canonical application/servpher+json representation is encoded deterministically using Base64 and can be decoded by the client. This is useful during development, but it is not yet the finished interface intended to replace METACODES.PRO.
The long-term direction separates two concerns:
┌───────────────────────────────────┐
│ │
│ End-user presentation │
│ │
├───────────────────────────────────┤
│ ▼ Optional diagnostic information │
│ Metadata │
│ Relationships │
│ Projection │
│ Raw representation │
└───────────────────────────────────┘
The actual content should become primary and diagnostic details should remain available through an optional developer overlay. Most importantly, the SPA is deliberately not privileged: It must communicates exclusively through the same public interface available to any other client. This provides a useful architectural test. Whenever the SPA needs information that is unavailable through the public Projection model, the preferred solution is not to introduce a private frontend endpoint, instead the public representation should be reconsidered.
Only when the reference client works without architectural shortcuts can the public interface be considered sufficiently expressive.
Eventually a reader-oriented renderer and theme should present blog articles, navigation, archives, tags and other website structures. The current debugging client supplies the groundwork and exposes weaknesses before they disappear behind a polished interface.
Where SERVPHER stands today
SERVPHER remains a work in progress and it is not yet ready to replace this website. Nevertheless, several fundamental parts now cooperate:
- Filesystem and classpath resources contribute to one
Node Graph
- Filename semantics define ordering, visibility,
Bookmarks and Index roles
Sidecars and markdown front matter enrich MetadataProjection queries shape representations- Multiple strategies represent structured and raw content
- Binary and textual resources share a stream-oriented abstraction
- Dynamic
Handlers participate in the same domain model
- Transport-independent representations separate
Projections from HTTP
- The bundled
SPA explores the graph through the public interface
The architecture has reached a stage at which new requirements increasingly find a natural home instead of requiring a redesign. That is an encouraging milestone, but it is not a declaration that the project is finished.
The next steps are more visible to end users:
- A richer, content oriented
SPA
- Markdown rendering suitable for articles
- A theme and layout system
- Blog navigation
- Archives, categories and tags
- Search
- Production ready diagnostics
- Migration support for existing
METACODES.PRO content
- Caching and conditional requests
The existing website is therefore both the motivation and the proving ground. A replacement will only be convincing when it handles the real articles, images, downloads, Metadata and navigation accumulated over many years without forcing that content into another cumbersome machinery.
The goal is not to replace Jekyll merely with another generator-the goal is to make the generator unnecessary.
Growing a platform instead of hard-coding a blog
One temptation would be to tailor SERVPHER directly around the present structure of METACODES.PRO. That might produce a replacement more quickly but it would also risk embedding today’s website decisions into tomorrow’s architecture. Instead, SERVPHER is intended to become a platform that applications tailor through explicit extension points:
Scanners discover additional information sourcesProcessors enrich the graphHandlers generate informationProjection strategies introduce new viewsMetadata describes application-specific semanticsSPA renderers present additional media types- Themes customize the appearance
The blog should become one application of the platform and not the hidden shape governing every architectural decision. This approach takes more time and it also produces more architectural discussions and occasionally replaces implementations that previously appeared complete. Yet, the resulting concepts have repeatedly become simpler and more general. Directories becoming content-bearing Nodes solved more than blog landing pages, Handlers solved more than generated files, Projection representations solved more than HTTP response construction and the Node Graph solved more than filesystem navigation.
A sound abstraction should enable the immediate use case without being defined solely by it.
The relationship between Gopher and SERVPHER becomes clearest when comparing their respective centers. Gopher organizes access around resources and hierarchical menus. SERVPHER organizes information around Nodes and relationships. Gopher lets a client traverse a distributed information space. SERVPHER aims to let clients observe and project a semantic information graph. Gopher’s radical simplicity came partly from refusing to make everything part of the protocol: Presentation remained largely a client concern, servers exposed resources and menus and clients decided how to display them.
SERVPHER follows a related instinct:
- Storage should not define presentation
- Presentation should not define the domain
HTTP should not define information- The reference frontend should not receive privileged access
- A resource should remain meaningful independently of its current representation
The implementations are separated by decades of technological development and solve different problems, nevertheless, the architectural sympathy is recognizable:
Gopher menu ─▸ Navigable resource hierarchy ─▸ SERVPHER node graph ─▸ Queryable information model ─▸ Transport-independent projections
Where Gopher exposed a remarkably coherent resource space, SERVPHER attempts to expose a coherent information space. This is the idea I hope to preserve while adding the capabilities required by a modern content platform.
The intend remains clear: At some point, this page should no longer be generated by Jekyll. Its Markdown source should be discovered by SERVPHER, enriched with Metadata, placed within the Node Graph and projected into a representation appropriate for the reader. The website should become a tailored view of that information rather than a build artifact produced by a tightly coupled toolchain.
Conceptually, the future flow may resemble:
Markdown articles ─▸ Filesystem scanner ─▸ Metadata processors ─▸ Node graph ─▸ Projection query ─▸ Blog representation ─▸ METACODES.PRO theme ─▸ Reader
The same article may remain simultaneously accessible as:
- Raw markdown
- Canonical
SERVPHER JSON
- Rendered
HTML
- A simplified representation for another client
- A future machine-readable
Projection
None of these representations owns the article as they merely are different observations of the same Node. This is where the initial inspiration from Gopher and the current architecture of SERVPHER meet: Gopher demonstrated how compelling a navigable information space could be when resources and hierarchy were treated as primary concepts and SERVPHER asks how far this principle can be carried when Nodes may originate from files, generated content, remote services or entirely virtual capabilities-and when every consumer may request an appropriate Projection of the same graph.
An ongoing architectural experiment
SERVPHER is not an announcement of a completed product as it is a project beginning to find its shape. Several details will change, classes will be renamed, interfaces will evolve and some implementations will be replaced. New requirements arising from the migration of METACODES.PRO will undoubtedly expose concepts that are currently still missing. The important milestone is not that all features are available. The important milestone is that the project now has an architectural direction against which new decisions can be evaluated:
Information Sources ─▸ Scanning ─▸ Processing ─▸ Node Graph ─▸ Projection Query ─▸ Projection ─▸ Representation ─▸ Transport ─▸ Client
Each stage answers a different question:
- What information exists?
- What does the information mean?
- How is it related?
- How should a client observe it?
- How should that observation be represented?
- How should the representation be delivered?
The architecture has repeatedly improved (and will continue to do so) not by accumulating larger components, but by discovering more precise concepts. This has led to a recurring question during development:
Have we discovered another domain concept?
As long as SERVPHER continues asking that question, I expect it to remain an interesting project even before it finally serves this blog.
Conclusion
SERVPHER began as an attempt to serve Markdown documents from a directory. Gopher supplied part of the inspiration: A server may expose a simple, navigable information space without owning its final presentation. Jekyll supplied the concrete problem: My existing blog works, but maintaining the machinery that generates it has become increasingly cumbersome. Between these two starting points, another idea has emerged. Content need not be organized around generated pages, framework controllers or storage technologies. It can be modeled once as a graph of information and projected differently for every consumer. SERVPHER is still some distance away from replacing METACODES.PRO. The architecture is beginning to suggest, however, that such a replacement will not merely exchange one website generator for another. Instead, the blog may become one projection of a broader information platform. Perhaps one day this article will be delivered by the very project it introduces. Until then, it remains a report from an ongoing architectural experiment:
From Gopherspace, through a Jekyll-driven blog, toward a projectable graph of information.
]]>