{"id":51252897,"url":"https://github.com/semantic-namespace/atlas","last_synced_at":"2026-06-29T08:00:42.881Z","repository":{"id":332148472,"uuid":"1120691291","full_name":"semantic-namespace/atlas","owner":"semantic-namespace","description":"Atlas rethinks how system entities are identified. Query, validate, and visualize your system semantics as a single graph ","archived":false,"fork":false,"pushed_at":"2026-05-26T10:12:56.000Z","size":1246,"stargazers_count":24,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-28T19:05:00.628Z","etag":null,"topics":["architecture","atlas","clojure","clojurescript","registry","semantics"],"latest_commit_sha":null,"homepage":"https://github.com/semantic-namespace/atlas","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semantic-namespace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T18:39:31.000Z","updated_at":"2026-06-14T07:18:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semantic-namespace/atlas","commit_stats":null,"previous_names":["semantic-namespace/atlas"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/semantic-namespace/atlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semantic-namespace%2Fatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semantic-namespace%2Fatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semantic-namespace%2Fatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semantic-namespace%2Fatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semantic-namespace","download_url":"https://codeload.github.com/semantic-namespace/atlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semantic-namespace%2Fatlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34918101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","atlas","clojure","clojurescript","registry","semantics"],"created_at":"2026-06-29T08:00:42.030Z","updated_at":"2026-06-29T08:00:42.873Z","avatar_url":"https://github.com/semantic-namespace.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Status: Proof of Concept (Alpha)**\n\u003e\n\u003e Atlas is in early development. APIs may change. Feedback welcome!\n\n# Atlas\n\n\u003e \"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.\"\n\u003e\n\u003e — [clojure.org/about/spec](https://clojure.org/about/spec#_expressivity_proof)\n\nA semantic registry for software architecture. Describe your system's components, functions, and relationships using **compound identities** (sets of semantic aspects), then query, validate, and visualize your architecture as a single queryable graph.\n\n\n## The Problem\n\nUnderstanding, maintaining, and communicating system design are constant challenges in any medium-to-large project. Complexity grows with every new feature, rule, or condition, eventually overwhelming developers with unmanageable cognitive load.\n\nIn most software systems, \"identity\" is bound to **place** - a thing's name implies where it lives (folder, file, namespace, memory address). This is an accident of hardware history, not a conceptual necessity.\n\nWhat if identity was determined by **semantics** - what something means and how it relates to other things?\n\n## What Atlas Does\n\nAtlas offers a semantic registry and tooling layer for software architecture: you describe components, functions, endpoints, protocols, and business concepts as **compound identities** (sets of aspects) plus structured properties - without thinking about implementation details.\n\n```clojure\n;; A function's identity IS its semantic meaning\n(registry/register!\n  :fn/validate-token                    ; dev-id (for humans)\n  :atlas/execution-function             ; entity type\n  #{:domain/auth                        ; semantic aspects\n    :operation/validate\n    :tier/service}\n  {:execution-function/context [:auth/token]\n   :execution-function/response [:auth/valid? :auth/user-id]\n   :execution-function/deps #{:component/oauth-provider}})\n```\n\nFrom this registry, Atlas can:\n- **Query** - Find all entities in `:domain/auth`, all `:tier/service` functions, etc.\n- **Validate** - Check that data flows are satisfiable, dependencies exist, tiers are respected\n- **Visualize** - Explore the semantic graph interactively\n- **Document** - Generate architecture docs from the registry\n\nIt's a **data-first approach** where the system's structure is queryable, visualizable, and validated via a shared ontology - rather than hard-coded diagrams or ad-hoc documentation.\n\n## Technical Approach\n\nAtlas embraces Clojure namespaced keywords (like `clojure.spec`) and depends on a mutable global registry (also like `clojure.spec`). Beyond that, Atlas pursues two intents:\n\n1. **Entities as Datalog facts** - Represent your system entities (functions, components, endpoints, etc.) as Datalog facts, making them queryable via Datalog.\n\n2. **Semantics as Datalog facts** - Represent semantic relations as Datalog facts, so entities and their meanings become a single queryable graph.\n\nEvery identity and relation lives in a global registry that can be translated into a graph database, queryable via Datalog.\n\n## Quick Start\n\n### Installation\n\nAdd to your `deps.edn`:\n\n\n```clojure\n{:deps {com.github.semantic-namespace/atlas {:mvn/version \"0.0.1-SNAPSHOT\"}}\n```\n\n\n### Basic Usage\n\n```clojure\n(require '[atlas.registry :as registry])\n(require '[atlas.query :as query])\n(require '[atlas.ontology :as ont])\n\n;; Register entity types first\n(ont/register-entity-types!)\n\n;; Register a component\n(registry/register!\n  :component/database\n  :atlas/structure-component\n  #{:tier/foundation :domain/storage}\n  {:component/provides [:db/query :db/transact]})\n\n;; Register a function that uses it\n(registry/register!\n  :fn/get-user\n  :atlas/execution-function\n  #{:domain/users :tier/service}\n  {:execution-function/context [:user/id]\n   :execution-function/response [:user/data]\n   :execution-function/deps #{:component/database}})\n\n;; Register an API endpoint\n(registry/register!\n  :endpoint/get-user\n  :atlas/interface-endpoint\n  #{:domain/users :tier/api :http/get}\n  {:endpoint/context [:http/path-params]\n   :endpoint/response [:http/response]\n   :endpoint/deps #{:fn/get-user}})\n```\n\n### Querying\n\n```clojure\n;; Find all entities in auth domain\n(query/find-by-aspect @registry/registry :domain/auth)\n\n;; Find by multiple aspects\n(query/find-by-aspect @registry/registry #{:domain/users :tier/service})\n\n;; Get an entity's semantic identity\n(registry/identity-for :fn/get-user)\n;; =\u003e #{:atlas/execution-function :domain/users :tier/service}\n```\n\n### Checking Invariants\n\n```clojure\n(require '[atlas.invariant :as inv])\n\n;; Check all architectural invariants\n(inv/check-all)\n\n;; Get human-readable report\n(inv/report)\n```\n\n## Core Concepts\n\n### Compound Identity\n\nEvery entity has a **compound identity** - a set of qualified keywords:\n\n```clojure\n#{:atlas/execution-function :domain/auth :operation/validate :tier/service}\n```\n\nThis set **is** the entity's semantic meaning. It enables:\n- Multi-dimensional querying (find by any aspect combination)\n- Semantic similarity (how related are two entities?)\n- Architectural reasoning (what domains touch what tiers?)\n\n### Entity Types\n\nBuilt-in types (register your own with `:atlas/type`):\n- `:atlas/execution-function` - Business logic functions\n- `:atlas/interface-endpoint` - API endpoints\n- `:atlas/structure-component` - Infrastructure components\n- `:atlas/data-schema` - Data structures\n- `:atlas/interface-protocol` - Protocols/interfaces\n\n### Data Flow\n\nFunctions declare what data they consume and produce:\n\n```clojure\n{:execution-function/context [:user/id :auth/token]   ; inputs\n :execution-function/response [:user/data :user/roles] ; outputs\n :execution-function/deps #{:component/db}}            ; dependencies\n```\n\nAtlas validates that every input is produced somewhere and every output is consumed or terminal.\n\n### Tiers\n\nStandard architectural tiers:\n- `:tier/foundation` - Components (DB, cache, external APIs)\n- `:tier/service` - Business logic functions\n- `:tier/api` - HTTP endpoints\n\nAtlas enforces tier boundaries (services can't skip to foundation, etc.).\n\n## Tooling\n\n### POC Visual Explorer\n\nTwo interactive visualization modes for exploring semantic registries. Start from REPL or use shadow-cljs for development:\n\n**From REPL:**\n```clojure\n(require '[atlas.atlas-ui.server :as ui])\n\n;; Version 1: Graph view (multi-aspect queries, lenses)\n(ui/start! {:ui-version :v1})  ; Opens http://localhost:8082\n\n;; Version 2: Dual map view (aspects + entities)\n(ui/start! {:ui-version :v2})  ; Opens http://localhost:8082\n```\n\n**Development with shadow-cljs:**\n```bash\ncd ui\n\n# Version 1 (port 8081)\nnpx shadow-cljs watch atlas-ui\n\n# Version 2 (port 8083)\nnpx shadow-cljs watch atlas-ui-v2\n```\n\nFeatures: interactive querying, lens-based filtering, dependency analysis, shareable URLs.\n\nSee [Visual Explorer docs](docs/visual-explorer.md) for full documentation and development setup.\n\n### Emacs Integration (PoC)\n\n![Emacs transient menu](https://github.com/user-attachments/assets/1af2d36d-6fb9-44b8-b77d-2b262e396da0)\n\nExplore registries directly from your editor via CIDER:\n\n```elisp\n  (add-to-list 'load-path \"..../semantic-namespace/atlas/emacs\")\n  (require 'atlas)\nM-x atlas  ; Opens transient menu\n```\n\nFeatures: entity browsing, data flow tracing, invariant checking, completion.\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) - 5-minute tutorial\n- [Core Concepts](docs/concepts.md) - Detailed concept explanations\n- [API Reference](docs/api-reference.md) - Function reference\n- [Examples](docs/examples.md) - Annotated example registries\n- [Emacs Integration](docs/emacs-integration.md) - IDE support via CIDER\n- [Visual Explorer](docs/visual-explorer.md) - Browser-based graph UI\n\n## Example Applications\n\nSee `test/app/` for complete examples:\n- `calendar_availability.clj` - Calendar system with OAuth, users, events\n- `cart.clj` - Shopping cart with sessions, payments\n- `pet_shop.clj` - Multi-domain system with external integrations\n\n## Development\n\n### Core Library\n\n```bash\n# Start REPL with everything loaded\nclojure -M:dev\n\n# Run tests\nclojure -M:test\n\n# Build JAR\nclojure -T:build jar\n```\n\n### Visual Explorer UI\n\nSee [Visual Explorer docs](docs/visual-explorer.md) for full setup. Quick start:\n\n```bash\ncd ui\n\n# Install dependencies (first time only)\nnpm install\n\n# Development with hot-reload\nnpx shadow-cljs watch atlas-ui    # v1 on port 8081\n# or\nnpx shadow-cljs watch atlas-ui-v2  # v2 on port 8083\n\n# Compile for production\nnpx shadow-cljs release atlas-ui\nnpx shadow-cljs release atlas-ui-v2\n```\n\n## License\n\nMIT - See [LICENSE](LICENSE)\n\n## Status \u0026 Roadmap\n\nThis is an early proof-of-concept exploring semantic approaches to architecture description. Current limitations:\n\n- API stability not guaranteed\n- Documentation in progress\n- Tooling (UI, Emacs) is experimental\n- Performance not yet optimized for large registries\n\nFeedback, ideas, and contributions welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemantic-namespace%2Fatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemantic-namespace%2Fatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemantic-namespace%2Fatlas/lists"}