From 1e81f2b904953ca4f6f44fcfad653a1f2fcf4792 Mon Sep 17 00:00:00 2001 From: Matt Beanland Date: Sat, 23 May 2026 22:14:52 +0930 Subject: [PATCH] fix README.md --- README.md | 55 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0ffb9dc..a838bc4 100644 --- a/README.md +++ b/README.md @@ -13,38 +13,50 @@ SPDX-License-Identifier: MIT [Diffo](https://github.com/diffo-dev/diffo) is a Telecommunications Management Forum (TMF) Service and Resource Manager, built for autonomous networks. -This repo contains two independent example domains, each modelling a different slice of a telco network. +This repo contains two independent example domains, plus an orientation to the underlying Diffo Provider primitives. Read in this order: -## NBN Domain +1. **[The Access Domain](documentation/domains/access.md)** — the warm-up. A single fictional telco delivering DSL service over copper to its own customers. Five resources, one service, a small state machine. Walks the pattern end-to-end. +2. **[The Provider Domain](documentation/domains/provider.md)** — lifts the lid on the primitives Access has been using the whole time (Specification, Instance, typed Characteristics, Pools, Assignments, Relationships, Place, Party, state machine, the TMF JSON encoder). +3. **[The NBN Domain](documentation/domains/nbn.md)** — the deeper case. A fictional wholesale broadband network shared by many Retail Service Providers. Adds multi-tenancy via Ash Policy, a longer delivery chain, and the named-vs-metrics characteristic pattern with cross-resource inheritance. -A declarative model of a fictional NBN Ethernet access hierarchy — NbnEthernet, UNI, AVC, NTD, CVC, NNI Group, and NNI — built entirely with the Diffo Provider Instance DSL. Includes multi-tenancy via Ash Policy: each RSP can only see and manage the resources they own. +Each domain ships with a runnable livebook. -[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fdev%2Fdocumentation%2Fdomains%2Fdiffo_example_nbn.livemd) +## Access Livebook -The livebook walks through provisioning a complete NBN Ethernet access circuit, selecting an RSP to operate as, and demonstrating how the `mine` actions propagate technology, speeds, CVLAN, and port assignments up the resource hierarchy. +[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fmain%2Fdocumentation%2Fdomains%2Fdiffo_example_access.livemd) -## Access Domain +End-to-end scenario through the code-interface — exchange shelf with line cards, a customer access path through copper, qualify and design a DSL service for the subscriber, then read the inheritance chain. -A copper-network equivalent covering DSL access services — Cable, Card, Path, and Shelf. Explore `lib/access/` for the domain model. +## NBN Livebook + +[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fmain%2Fdocumentation%2Fdomains%2Fdiffo_example_nbn.livemd) + +The wholesale story — pick an RSP, build the shareable NNI Group / CVC, provision a subscriber's NBN Ethernet access end-to-end, then read the full delivery chain through inheritance and the live metrics on each resource. + +## API reference (auto-generated) + +- [Access Domain API](documentation/domains/_access_api.md) — every code-interface function on `DiffoExample.Access`. +- [NBN Domain API](documentation/domains/_nbn_api.md) — every code-interface function on `DiffoExample.Nbn`. + +Both are regenerated from the domain DSL with `mix gen.api_docs`. ## Installation -If [available in Hex](https://hex.pm/docs/publish), the package can be installed -by adding `diffo_example` to your list of dependencies in `mix.exs`: +The package can be installed by adding `diffo_example` to your list of dependencies in `mix.exs`: ```elixir def deps do [ - {:diffo_example, "~> 0.0.2"} + {:diffo_example, "~> 0.2"} ] end ``` -You need [Neo4j](https://github.com/neo4j/neo4j) available. We recommend the Neo4j Community 5 latest, available at [Neo4j Deploymnent Centre](https://neo4j.com/deployment-center/) which can be installed locally. You can also configure connection to a cloud based database service such as [Neo4j AuraDB](https://neo4j.com/product/auradb/). +You need [Neo4j](https://github.com/neo4j/neo4j) available. We recommend the Neo4j Community 5 latest, available at the [Neo4j Deployment Centre](https://neo4j.com/deployment-center/) which can be installed locally. You can also configure connection to a cloud-based database service such as [Neo4j AuraDB](https://neo4j.com/product/auradb/). ## Contributions -Contributions are welcome, please start with an [issue](https://github.com/diffo-dev/diffo_example/issues) +Contributions are welcome, please start with an [issue](https://github.com/diffo-dev/diffo_example/issues). ## Acknowledgements @@ -52,18 +64,17 @@ Thanks to my colleagues in the Telco industry. Thanks to the vibrant Elixir and Ash communities, and in particular the [Ash Core](https://github.com/ash-project) for [ash](https://github.com/ash-project/ash) 🚀 -Thanks to [Florin Patrascu](https://github.com/florinpatrascu) for [bolt_sips](https://github.com/florinpatrascu/bolt_sips) and[Luis Sagastume](https://github.com/sagastume) for [boltx](https://github.com/sagastume/boltx), both forerunners of [bolty](https://github.com/diffo-dev/bolty) the bolt driver for neo4j. +Thanks to [Florin Patrascu](https://github.com/florinpatrascu) for [bolt_sips](https://github.com/florinpatrascu/bolt_sips) and [Luis Sagastume](https://github.com/sagastume) for [boltx](https://github.com/sagastume/boltx), both forerunners of [bolty](https://github.com/diffo-dev/bolty) — the Bolt driver for Neo4j. Thanks to the [Neo4j Core](https://github.com/neo4j) for [neo4j](https://github.com/neo4j/neo4j) and pioneering work on graph databases. ## Links -[Diffo TMF Service and Resource Manager](https://github.com/diffo-dev/diffo) -[Diffo.dev](https://www.diffo.dev) -[Ash Neo4j Datalayer](https://github.com/diffo-dev/ash_neo4j) -[bolty](https://github.com/diffo-dev/bolty) -[Neo4j Deployment Centre](https://neo4j.com/deployment-center/) -[Ash Outstanding Extension](https://github.com/diffo-dev/ash_outstanding) -[Outstanding Elixir Protocol](https://github.com/diffo-dev/outstanding) -[TMF](https://www.tmforum.org) - +- [Diffo TMF Service and Resource Manager](https://github.com/diffo-dev/diffo) +- [Diffo.dev](https://www.diffo.dev) +- [Ash Neo4j Datalayer](https://github.com/diffo-dev/ash_neo4j) +- [bolty](https://github.com/diffo-dev/bolty) +- [Neo4j Deployment Centre](https://neo4j.com/deployment-center/) +- [Ash Outstanding Extension](https://github.com/diffo-dev/ash_outstanding) +- [Outstanding Elixir Protocol](https://github.com/diffo-dev/outstanding) +- [TMF](https://www.tmforum.org)