Atlas: semantic discipline that scales
Table of Contents
expressivity > proof
"There is no reason to limit our specifications to what we can prove, yet that is primarily what type systems do. There is so much more we want to communicate and verify about our systems."
1 The Idea
Most software architectures rely on conventions, diagrams, and documentation to express intent—but none of these are enforced, queryable, or tightly coupled to change. As systems evolve, architectural meaning drifts: names stay the same while assumptions quietly change.
Atlas explores a different approach: treating architecture as semantic data. Instead of encoding intent indirectly through file structure or prose, Atlas makes meaning explicit through compound semantic identities, validated by executable rules and queryable as a database.
The goal is not documentation, diagrams, or code generation.
The goal is semantic discipline that scales.
2 Architecture as Semantic Data
Atlas builds on a simple premise: identity should be defined by what something means, not where it lives.
Any system entity is registered with:
- an entity type
- a set of semantic aspects (domain, tier, effect, requirements, integration style)
- structured properties describing any entyt type requirement, including dependencies, data flow, etc
This registry is the architectural truth. Everything else—validation, analysis, visualization—is derived.
2.1 Compound Semantic Identities
A compound identity is a set of orthogonal semantic aspects that together describe architectural meaning. These aspects are not comments or tags; they are machine-readable and governed.
The key shift: names no longer carry architectural meaning implicitly. Meaning is explicit, enumerable, and enforceable.
This makes architecture explorable across dimensions instead of frozen into hierarchies.
3 Four Reinforcing Mechanisms
Atlas works because four mechanisms form a closed feedback loop.
3.1 1. Invariants: Semantic Governance as Code
Architectural rules are encoded as executable invariants over the registry.
These invariants validate semantic consistency, not runtime behavior:
- dependency legality
- tier boundaries
- data-flow satisfiability
- protocol usage
- cross-cutting requirements
Violations are detected deterministically. Enforcement can be wired into CI, but Atlas itself remains descriptive: it models architecture, it does not replace code.
This turns conventions into infrastructure.
3.2 2. Datalog: Architecture as a Queryable Database
The registry is compiled into a Datalog database, enabling semantic analysis:
- impact analysis
- reachability
- dependency chains
- pattern discovery
- compliance verification
Datalog is not an implementation detail; it is the analytical backbone that makes architectural knowledge computable.
3.3 3. IDE & Visualization: Ergonomic Correctness
Tooling surfaces semantics where developers work:
- aspect discovery and autocomplete
- navigation across semantic relationships
- real-time invariant feedback
- visual exploration of architecture
Correctness becomes the path of least resistance.
3.4 4. LLM + MCP (Planned): Conversational Architecture
LLMs act strictly as interfaces, not authorities.
Via MCP or directyly using the registry as edn and some trained atlas prompt, an LLM can translate questions into registry queries and reason over actual architectural data. The value is not design generation, but:
- pattern surfacing
- drift detection
- impact explanation
- semantic authoring assistance
All answers remain grounded in the registry.
4 Registry Versioning (Planned): Semantic History
Adding registry versioning transforms Atlas from a snapshot tool into a semantic ledger.
Instead of tracking textual diffs, Atlas can track typed semantic changes:
- aspects added or removed
- dependency rewiring
- scope or responsibility shifts
5 Pluggable Ontologies: Meaning Without Lock-in
Ontologies in Atlas are pluggable.
This prevents meanings from becoming frozen or outdated:
- domain-specific vocabularies
- ontology evolution over time
- multiple semantic perspectives over the same registry
- experimentation without global breakage
The registry stores facts. Ontologies interpret meaning.
Together with versioned registries, this allows semantic time travel: understanding what something meant, when, and under which conceptual frame.
6 When This Makes Sense
Atlas is infrastructure. It has real costs:
- initial modeling effort
- ontology design
- semantic thinking overhead
7 Status
Atlas is an early experiment:
[X]semantic registry is functional[X]invariants and Datalog analysis work[X]editor and visual tooling exist[X]ontology system is extensible[ ]LLM + MCP integration (planned)[ ]registry versioning (planned)
Expect APIs to change. Feedback is part of the design process.
8 Get Involved
Interested in exploring these ideas?
- Public repository with documentation
- Working examples (calendar, cart, pet shop systems)
- Emacs integration available
- Feedback and discussion welcome https://github.com/semantic-namespace/discussions
—