Scribes were an elite in ancient societies, highly regarded and holding special social status. They were disciplined and known for their excellent craftsmanship in writing laws, copying documents, and other related tasks.
The motivation to create the Elixir Scribe tool was to encourage developers to write Clean Code in a Clean Software Architecture, to enable them to know in seconds all domains, resources, and actions used in a project, while reducing complexity and contributing for less technical debt.
The Elixir Scribe tool enables developers to go from zero to hero in no time, while empowering their craftsmanship and professionalism to reach new levels never imagined before or thought to not be easy to achieve.
Don't just be a Developer or Engineer, become a Scribe Developer and Engineer ð
Curious about the next release? Be no more: check here for details and dates.
[!IMPORTANT]
â The Elixir Scribe tool is not about implementing Domain Driven Design (DDD), but may share some similarities.
[!TIP]
â Clone the branch
WIP
to be on the bleeding edge of the current work being done.
â Be prepared for buggy code. It may work or not.
â Be ready for breaking changes, which can happen at any moment.[!CAUTION]
â NEVER base your work on the
WIP
branch. Code and features may disappear.
â Push forces can occur at any commit, thus commit history will be broken.
The Elixir Scribe generators will help developers to effortless organize their code by Domain, Resource and all possible actions on the Resource to reduce complexity and technical debt.
This reduction in complexity translates into fewer bugs and makes it easier to add new features and implement bug fixes when they arise. Consequently, this results in less maintenance and technical debt across the lifetime of a project, leading to a more robust and easier-to-work-with code-base.
Ultimately, this enhances developer experience, velocity and productivity. This is a win win for both the business and developers.
A Clean Software Architecture MUST allow developers to understand in seconds, or in a couple of minutes, all Domains, Resources and actions of the project they are working on.
Can you grasp, in seconds, all domains, resources, and actions in your current large professional or side projects? With the Elixir Scribe folder structure you will always reply YES to the this question.
Let's do an exercise. How much time do you need to know all domains, resources and actions from the below fictitious acme
app?
The below folder structure reflects the Elixir Scribe generator used in the Quickstart:
$ tree -d -L 5 lib
lib
âââ my_app
â âââ domains
â âââ catalog
â â âââ category
â â â âââ create
â â â âââ delete
â â â âââ edit
â â â âââ list
â â â âââ new
â â â âââ read
â â â âââ update
â â âââ product
â â âââ create
â â âââ delete
â â âââ edit
â â âââ export
â â âââ import
â â âââ list
â â âââ new
â â âââ read
â â âââ update
â âââ warehouse
â âââ stock
â âââ export
â âââ import
âââ my_app_web
âââ components
â âââ layouts
âââ domains
âââ catalog
â âââ category
â â âââ create
â â âââ delete
â â âââ edit
â â âââ list
â â âââ new
â â âââ read
â â âââ update
â âââ product
â âââ create
â âââ delete
â âââ edit
â âââ export
â âââ import
â âââ list
â âââ new
â âââ read
â âââ update
âââ warehouse
âââ stock
âââ export
âââ import
Domains: catalog, warehouse
Resources: category, product, stock
Actions: create, delete, edit, export, import, list, new, read, update
So, how many seconds did it took you to have an overview of the project and understand all it's Domains, Resources and Actions? How much time do you think you would spend looking through the code-base to find where to fix a bug to export
a Product or to add a new feature to the Category resource?
This is a very simplistic view of a project. Now, imagine reaping the benefits of this folder structure implemented on your huge code-base, which may now contain dozens, hundreds, or even thousands of resources (yes, I worked in such a project), each with potentially more actions than the ones exemplified here.
Take a moment to compare this folder structure with the traditional ones used in any project you worked so far, be it an Elixir / Phoenix project or not, which often condenses several resources and all their actions into a single module / class, without even care about Domain boundaries.
Writing Clean Code relies on several aspects, and one of them is to follow the Single Responsibility Principle, which is encouraged by the Elixir Scribe tool, when it forces the developer to split all possible actions on a Resource into a single module by action on a Resource.
The Developer can still manage to mix responsibilities in the action module for the Resource. For example, any access to a third party service should be delegated to another module. The action module should do only one thing, to handle the data as per the businesses rules.
The Elixir Scribe tool doesn't enforce an architecture inside the action folder, leaving the Developer free to apply the best one for it's use case. For example, the module generated by the Elixir Scribe tool inside the action folder may be used as an entry-point to orchestrate all required steps to perform the action on the Resource, which will be done in other modules to follow the Single Responsibility Principle, reduce complexity per module, resulting in a Clean Code that it's easier to understand and maintain.
Can you now understand why Elixir Scribe encourages developers to write Clean Code in a Clean Software Architecture?
The main benefits of using the Elixir Scribe Tool to create and maintain Elixir and Phoenix projects:
The Elixir Scribe package can be installed
by adding elixir_scribe
to your list of dependencies in mix.exs
:
def deps do
[
{:elixir_scribe, ">= 0.1.0", only: :dev, runtime: false}
]
end
IMPORTANT: Not merged yet to the main branch.
Let's create a fictitious Online Shop to exemplify how to use the Elixir Scribe tool:
mix phx.new my_app --database sqlite3
Now let's use the Elixir Scribe generators to create the domain Catalog
and add to it the resource Category
with the default actions:
mix scribe.gen.html Catalog Category categories name:string desc:string
Elixir Scribe default actions: create, delete, edit, list, new, read, update
Let's add to the domain Catalog
the resource Product
with custom actions on top of the default actions:
mix scribe.gen.html Catalog Product products name:string desc:string --actions import,export
Let's add the domain Warehouse
with the resource Stock
without default actions. We will need to provide custom actions:
mix scribe.gen.html Warehouse Stock stocks product_id:integer quantity:integer --actions import,export --no-default-actions
The docs can be found at https://hexdocs.pm/elixir_scribe.
Documentation is generated with ExDoc.
The Elixir Scribe tool is highly opinionated, therefore I ask you to first open a discussion to propose your idea to avoid working and then seeing the PR refused.
The roadmap is extensive and due to the continuous high efforts and commitments to develop and maintain everything I may only provide some of the features to Sponsors and/or as Pro versions that will require a paid license.
The next release will be 0.3.0
, and will contain the following new generators:
scribe.gen.domain
scribe.gen.html
The release data is expected to be around the middle of July 2024.
This generators provide developers with the tools to go from zero to hero in no time, while following a Clean Software Architecture that encourages Clean Code when building their Apps or APIs.
scribe.gen.domain
scribe.gen.html
scribe.gen.live
scribe.gen.template
scribe.gen.*
.scribe.gen.home
scribe.gen.ci
mix format --dry-run --check-formatted
mix deps.unlock --check-unused
mix deps.audit
mix hex.audit
mix sobelow
mix credo
mix doctor
mix test --cover
scribe.gen.project
%ElixirScribe.ProjectSpecs{}
. scribe.gen.api
scribe.gen.auth
scribe.gen.oauth
scribe.gen.native
scribe.gen.static
scribe.gen.deploy
scribe.gen.admin