{"id":17279205,"url":"https://github.com/mainej/schema-voyager","last_synced_at":"2025-04-14T08:32:45.877Z","repository":{"id":42512222,"uuid":"252542175","full_name":"mainej/schema-voyager","owner":"mainej","description":"Visualize schema of Datomic and Datomic-like databases","archived":false,"fork":false,"pushed_at":"2024-04-20T22:00:11.000Z","size":2876,"stargazers_count":41,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-27T22:06:29.373Z","etag":null,"topics":["clojure","datomic","erd","schema","visualization"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mainej.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2020-04-02T19:01:30.000Z","updated_at":"2025-03-13T01:01:58.000Z","dependencies_parsed_at":"2024-04-20T23:19:04.881Z","dependency_job_id":"2ec3bec6-d4a6-4785-af69-3cf307aebcab","html_url":"https://github.com/mainej/schema-voyager","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mainej%2Fschema-voyager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mainej%2Fschema-voyager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mainej%2Fschema-voyager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mainej%2Fschema-voyager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mainej","download_url":"https://codeload.github.com/mainej/schema-voyager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248846015,"owners_count":21170882,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["clojure","datomic","erd","schema","visualization"],"created_at":"2024-10-15T09:16:27.265Z","updated_at":"2025-04-14T08:32:45.798Z","avatar_url":"https://github.com/mainej.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Schema Voyager\n\nSchema Voyager is a tool for documenting and exploring your [Datomic](https://www.datomic.com/) databases.\nIt imports your schema then displays it in a way that offers you and your team insights about the history and usage of your database.\n\nThe best way to get a feel for Schema Voyager is to play with it.\nTry exploring the live [mbrainz schema](https://mainej.github.io/schema-voyager/mbrainz-schema.html).\n\nIf you'd prefer a few screenshots, here's what it looks like.\nThe app starts with an overview of your schema, with attributes grouped into related collections.\n\n\u003cimg src=\"/doc/collections.png\" alt=\"Screenshot of the listing of aggregate and enum collections on the Schema Voyager homepage\" width=\"450\"/\u003e\n\nA configurable interactive diagram shows references between collections.\n\n\u003cimg src=\"/doc/collections_diagram.png\" alt=\"Screenshot of the connections diagram on the Schema Voyager homepage\" width=\"1004\"/\u003e\n\nDrill in to a collection to see the attributes it contains, as well as a more focused diagram of how those attributes are connected to other collections.\n\n\u003cimg src=\"/doc/aggregate.png\" alt=\"Screenshot of the attributes list and the connections diagram on the Schema Voyager aggregate page\" width=\"637\"/\u003e\n\nDrill further into an attribute, to see its properties.\n\n\u003cimg src=\"/doc/attribute.png\" alt=\"Screenshot of the attribute details on the Schema Voyager attribute page\" width=\"638\"/\u003e\n\n## Big Picture\n\nLet's establish a mental model of how Schema Voyager works.\n\nPresumably you can see where Schema Voyager gets some of its data.\nWhen you transact schema into Datomic, you give attributes a `:db/ident` along with a `:db/valueType` and `:db/cardinality`.\nYou can imagine how Schema Voyager would query Datomic for this data by looking up all the `:db/ident`s.\nIt could group similar attributes together and display their data.\n\nBut there's more going on here.\nSomehow Schema Voyager knows not only that `:track/artists` is a `:db.type/ref` attribute, but also that it refers to entities with attributes in the `:artist` namespace.\nIf you poked around in the [mbrainz schema](https://mainej.github.io/schema-voyager/mbrainz-schema.html) you might have noticed `:track/artistCredit` has been deprecated and superseded by `:track/artists`.\nReferences and deprecations aren't part of the regular schema that Datomic defines, so how does Schema Voyager know about these things?\n\nEnter **supplemental properties**.\nSchema Voyager defines supplemental properties that can be assigned to an attribute, properties which specify what the attribute references and whether it's deprecated, among other characteristics.\n\nIt's these supplemental properties that turn Schema Voyager into a living document about how your schema is being used, how attributes reference entities, which attributes are deprecated, and more.\n\n\n## Further Documentation\n\nOK, sounds good.\nHow do we get started?\n\n1. Start by learning [how to define](/doc/annotation.md) references, deprecations, and other supplemental properties.\n2. Then learn about [where to store](/doc/sources.md) your schema data, and how Schema Voyager reads these sources.\n3. When you're ready, learn [how to invoke](/doc/installation-and-usage.md) Schema Voyager to convert your schema data into an interactive web page.\n\nAfter you're up and running, [explore and share](/doc/exploring-and-sharing.md) your web page.\nOr [infer](/doc/datomic-inference.md) references and deprecations, kickstarting your supplemental schema.\n\n\n## Alternatives\n\n* [Hodur](https://github.com/hodur-org/hodur-engine) provides excellent [visualizations](https://github.com/hodur-org/hodur-visualizer-schema) of Datomic schema, but also expects to have greater control over schema installation and management.\n\n## Acknowlegements\n\n* [DataScript](https://github.com/tonsky/datascript) makes it much easier to design and import deeply interconnected data without worrying about how those connections might later be explored.\n  It's very useful to export an entire database from Clojure, then read and manipulate it from ClojureScript.\n  Also, it feels right to use Datalog to navigate Datomic data.\n* Though the HTML app isn't very dynamic, it was nice, as always, to build it with [reagent](https://reagent-project.github.io/) and [reitit](https://metosin.github.io/reitit/).\n* [Tailwind CSS](https://tailwindcss.com/) makes writing CSS _fun_.\n  Easy refactoring of styles, small CSS files, and the pages look nice, right?\n* It's amazing what goes into running GraphViz on the web.\n  Thanks to [Dorothy](https://github.com/cemerick/dorothy) for the tricky bits of DOT.\n  And to [HPCC-Systems](https://github.com/hpcc-systems/hpcc-js-wasm) for compiling GraphViz for the browser.\n  Judging from all the projects I tried but failed to get working, this is no small feat.\n  And to [jsdelivr](https://cdn.jsdelivr.net/) for hosting the WASM.\n* [shadow-cljs](http://shadow-cljs.org/) makes it a joy to write CLJS files alongside CLJ files.\n  Several client/server interaction tasks I had been putting off turned out to be trivial with shadow-cljs.\n\n## License\n\nCopyright © Jacob Maine.\nAll rights reserved.\n\nThe use and distribution terms for this software are covered by the Eclipse Public License 2.0 (https://opensource.org/licenses/EPL-2.0) which can be found in the file LICENSE at the root of this distribution.\nBy using this software in any fashion, you are agreeing to be bound by the terms of this license.\nYou must not remove this notice, or any other, from this software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmainej%2Fschema-voyager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmainej%2Fschema-voyager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmainej%2Fschema-voyager/lists"}