Skip to content

Commit 3f0e4fc

Browse files
Exadra37Exadra37
committed
Updated README with more detailed info about this project and its roadmap.
Signed-off-by: Exadra37 <exadra37@gmail.com>
1 parent 80eb66c commit 3f0e4fc

File tree

1 file changed

+202
-41
lines changed

1 file changed

+202
-41
lines changed

‎README.md‎

Lines changed: 202 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,61 +2,143 @@
22

33
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.
44

5-
The motivation to create the Scribe tool was to encourage developers to write cleaner code in a more organized software architecture, enabling them to know in seconds all domains (contexts), resources, and actions used in a project, while reducing complexity. 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 codebase. Ultimately, this enhances developer experience, velocity and productivity. This is a win win for both the business and developers.
5+
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.
66

7-
The Scribe tool enables developers craftsmanship and professionalism to reach new levels never imagined before or thought to not be easy to achieve.
7+
The Elixir Scribe tool enables developers craftsmanship and professionalism to reach new levels never imagined before or thought to not be easy to achieve.
88

99
Don't just be a Developer or Engineer, become a Scribe Developer and Engineer 🚀
1010

11+
> **IMPORTANT**: The Elixir Scribe tool is not about implementing Domain Driven Design (DDD), but may share some similarities.
12+
13+
14+
### TOC
15+
16+
* [Reduced Complexity Equals to Less Technical Debt](#reduced-complexity-equals-to-less-technical-debt)
17+
* [Clean Software Architecture](#clean-software-architecture)
18+
* [Clean Code](#clean-code)
19+
* [Benefits](#benefits)
20+
* [Installation](#installation)
21+
* [Quickstart](#quickstart)
22+
* [Documentation](#documentation)
23+
* [Contributing](#contributing)
24+
* [Roadmap](#roadmap)
25+
26+
27+
## Reduced Complexity Equals to Less Technical Debt
28+
29+
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.
30+
31+
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.
32+
33+
Ultimately, this enhances developer experience, velocity and productivity. This is a win win for both the business and developers.
34+
35+
[TOC](#toc)
36+
37+
38+
## Clean Software Architecture
39+
40+
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.
41+
42+
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.
43+
44+
Let's do an exercise. How much time do you need to know all domains, resources and actions from the below fictitious `acme` app?
45+
46+
The below folder structure reflects the Elixir Scribe generator used in the [Quickstart](#quickstart):
47+
48+
```text
49+
$ tree -d -L 5 lib
50+
51+
lib
52+
├── my_app
53+
│ └── domains
54+
│ ├── catalog
55+
│ │ ├── category
56+
│ │ │ ├── create
57+
│ │ │ ├── delete
58+
│ │ │ ├── edit
59+
│ │ │ ├── export
60+
│ │ │ ├── import
61+
│ │ │ ├── list
62+
│ │ │ ├── new
63+
│ │ │ ├── read
64+
│ │ │ └── update
65+
│ │ └── product
66+
│ │ ├── create
67+
│ │ ├── delete
68+
│ │ ├── edit
69+
│ │ ├── export
70+
│ │ ├── import
71+
│ │ ├── list
72+
│ │ ├── new
73+
│ │ ├── read
74+
│ │ └── update
75+
│ └── warehouse
76+
│ └── stock
77+
│ ├── export
78+
│ └── import
79+
└── my_app_web
80+
├── components
81+
│ └── layouts
82+
└── domains
83+
├── catalog
84+
│ ├── category
85+
│ │ ├── create
86+
│ │ ├── delete
87+
│ │ ├── edit
88+
│ │ ├── export
89+
│ │ ├── import
90+
│ │ ├── list
91+
│ │ ├── new
92+
│ │ ├── read
93+
│ │ └── update
94+
│ └── product
95+
│ ├── create
96+
│ ├── delete
97+
│ ├── edit
98+
│ ├── export
99+
│ ├── import
100+
│ ├── list
101+
│ ├── new
102+
│ ├── read
103+
│ └── update
104+
└── warehouse
105+
└── stock
106+
├── export
107+
└── import
11108
12-
## Folder Structure
109+
```
13110

14-
Can you grasp, in seconds, all domains, resources, and actions in your current large professional or pet projects?
111+
> **Domains:** catalog, warehouse
112+
> **Resources:** category, product, stock
113+
> **Actions:** create, delete, edit, export, import, list, new, read, update
15114
16-
With the Elixir Scribe folder structure you will always reply **YES** to the above question.
115+
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?
17116

18-
```
19-
lib/acme_shop
20-
├── catalog
21-
│ ├── category
22-
│ │ ├── assign
23-
│ │ ├── change
24-
│ │ ├── create
25-
│ │ ├── delete
26-
│ │ ├── get
27-
│ │ ├── list
28-
│ │ └── update
29-
│ └── product
30-
│ ├── assign
31-
│ ├── change
32-
│ ├── create
33-
│ ├── delete
34-
│ ├── get
35-
│ ├── list
36-
│ └── update
37-
└── warehouse
38-
└── inventory
39-
├── assign
40-
├── change
41-
├── create
42-
├── delete
43-
├── get
44-
├── list
45-
└── update
46-
```
117+
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.
118+
119+
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.
120+
121+
[TOC](#toc)
122+
123+
124+
## Clean Code
125+
126+
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.
127+
128+
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.
47129

48-
> Domains: catalog, warehouse - Resources: category, product, inventory - Actions: assign, change, ...
130+
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.
49131

50-
This is a very simplistic view of a project. Now, imagine reaping the benefits of this folder structure implemented on your extensive codebase, which may now contain dozens, hundreds, or even thousands of resources, each with potentially more actions than the ones exemplified here.
132+
Can you now understand why Elixir Scribe encourages developers to write **Clean Code** in a **Clean Software Architecture**?
51133

52-
Take a moment to compare and contemplate this folder structure with the traditional one used in an Elixir or Phoenix project, which often condenses several resources and all their actions into a single module (the context). Alternatively, in cases where contexts are not used, they may simply consist of large modules with only one resource and all its actions.
134+
[TOC](#toc)
53135

54-
Can you now understand why Elixir Scribe encourages developers to write cleaner code in a more organized software architecture?
55136

137+
## Benefits
56138

57-
## Benefits of Using the Elixir Scribe Tool to Create and Maintain Elixir and Phoenix Projects
139+
The main benefits of using the Elixir Scribe Tool to create and maintain Elixir and Phoenix projects:
58140

59-
* Know in seconds all domains (contexts), resources, and actions used in your project by just looking at the folder structure. This is priceless for anyone working on the project.
141+
* Know in seconds all domains, resources, and actions used in your project by just looking at the folder structure. This is priceless for anyone working on the project.
60142
* Newcomers to the project or anyone returning after a while can easily understand what the project is all about and quickly start working on new features or bugs (folder structure for the win).
61143
* The single responsibility principle is encouraged by the design of the folder structure, where a clear separation of domains, resources, and actions occurs, encouraging one resource action per module.
62144
* Helps to reduce tech debt due to the separation of concerns encouraged by the folder structure, which naturally guides developers to not mix new features into an existing module, whether it's a new domain, resource, or just an action on a resource.
@@ -65,6 +147,8 @@ Can you now understand why Elixir Scribe encourages developers to write cleaner
65147
* Each resource on a domain has a public API to avoid direct access to the underlying implementation of each resource. This removes cross-domain boundary calls into the internals of each resource implementation, preventing the coupling of domains, which is a significant source of technical debt and complexity in a codebase. The Resource public API MUST be used not only from other domains but also from within the domain itself. This will allow the internals of a resource in a domain to change as needed, provided that we do not affect the public API for it.
66148
* The folder structure is documentation that never lies about what domains (contexts), resources, and actions are available in your project, whether huge or small.
67149

150+
[TOC](#toc)
151+
68152

69153
## Installation
70154

@@ -74,20 +158,97 @@ by adding `elixir_scribe` to your list of dependencies in `mix.exs`:
74158
```elixir
75159
def deps do
76160
[
77-
{:elixir_scribe, "~> 0.1.0"}
161+
{:elixir_scribe, ">= 0.1.0", only: :dev}
78162
]
79163
end
80164
```
81165

166+
[TOC](#toc)
167+
168+
169+
## Quickstart
170+
171+
Let's create a fictitious Online Shop to exemplify how to use the Elixir Scribe tool:
172+
173+
```
174+
mix phx.new my_app --database sqlite3
175+
```
176+
177+
Now let's use the Elixir Scribe generators to create the domain `Catalog` and add to it the resource `Category` with the default actions:
178+
179+
```
180+
mix scribe.gen.html Catalog Category categories name:string desc:string --web Catalog
181+
```
182+
183+
> Elixir Scribe default actions: create, delete, edit, list, new, read, update
184+
185+
186+
Let's add to the domain `Catalog` the resource `Product` with custom actions on top of the default actions:
187+
188+
```
189+
mix scribe.gen.html Catalog Product products name:string desc:string --web Catalog --actions batch_create,batch_update
190+
```
191+
192+
Let's add the domain `Warehouse` with the resource `Iventory` without default actions. We will need to provide custom actions:
193+
194+
```
195+
mix scribe.gen.html Warehouse Inventory inventories name:string desc:string --web Warehouse --actions batch_create,batch_update --no-default-actions
196+
```
197+
198+
[TOC](#toc)
199+
82200

83201
## Documentation
84202

85203
The docs can be found at <https://hexdocs.pm/elixir_scribe>.
86204

87205
Documentation is generated with [ExDoc](https://github.com/elixir-lang/ex_doc).
88206

207+
[TOC](#toc)
208+
89209

90210
## Contributing
91211

92212
The Elixir Scribe tool is highly opinionated, therefore I ask you to first [open a discussion](https://github.com/Exadra37/elixir-scribe/discussions/new?category=ideas) to propose your idea to avoid working and then seeing the PR refused.
93213

214+
[TOC](#toc)
215+
216+
217+
## Roadmap
218+
219+
### Elixir Scribe Generators
220+
221+
- [ ] Mix task: `scribe.gen.domain`
222+
- [ ] Mix task: `scribe.gen.html`
223+
- [ ] Mix task: `scribe.gen.live`
224+
- [ ] Mix task: `scribe.gen.home`
225+
* Removes current default Home page.
226+
* Adds new Home page with links to each Domain and Resource.
227+
- [ ] Mix task: `scribe.gen.ci`
228+
* Generates a CI file for Github or Gitlab with at least the following:
229+
+ `mix format --dry-run --check-formatted`
230+
+ `mix deps.unlock --check-unused`
231+
+ `mix deps.audit`
232+
+ `mix hex.audit`
233+
+ `mix sobelow`
234+
+ `mix credo`
235+
+ `mix doctor`
236+
+ `mix test --cover`
237+
- [ ] Mix task: `scribe.gen.project` -> Generates all Domains, Resources and Actions from an Elixir Scribe spec module `%ElixirScribe.ProjectSpecs{}`.
238+
- [ ] Mix task: `scribe.gen.api`
239+
- [ ] Mix task: `scribe.gen.native`
240+
* Enables the project to be built for Desktop, Android and Apple.
241+
* Elixir libraries to build for native targets:
242+
+ [LiveView Native](https://github.com/liveview-native)
243+
+ [Elixir Desktop](https://github.com/elixir-desktop/desktop)
244+
+ [ExTauri](https://github.com/Exadra37/ex_tauri)
245+
- [ ] Mix task: `scribe.gen.admin`
246+
247+
### Improvements
248+
249+
- [ ] Optimize default HTMl layout and components for a more clean and usable UI.
250+
- [ ] Table headers in Bold
251+
- [ ] Highlight links in blue, not in bold (black).
252+
- [ ] Add Authentication by default to all pages, except Home page.
253+
- [ ] Add dynamic API key (only valid for one request)
254+
- [ ] Add Remote Configuration for mobile apps

0 commit comments

Comments
 (0)