👀 Do you want to develop semio with us? Then join our Weekly-Evening-Session every Tuesday starting at 6pm (UTC+1) on Discord 🍻
🧩 Design-Information-Modeling for Kit-of-Parts Architecture 🏘️
You want to 🧩 the next 🏛️🏘️🏢🏭🏫🏨⛪🕌 with 🤖? But 📐🔢🗣️👥🖱️⌨️ takes all your ⌚? Then try to 🧠 the 🧬 and let semio 💉🖥️✒️🖨️🪄🚀.
Note
Are you a user of semio? Then you probably want to visit our docs 👀
Glad to see you!
Let me walk you throw 🚶
🛍️ Products ↑
Do you wonder how semio is interopable? The reason are shared specification, ecosystems and components 🪢
✏️ sketchpad ↑
sketchpad is a simple-to-use, accessible and browser-based user interface for semio 🖱️
👀 studio ↑
A studio is a synchronous collaboriation environment for teams to work together on a project 🤝
🤖 assistant ↑
The assistant helps you on every step of the design process ✍️
🦗 grasshopper ↑
🐝 wasp ↑
🐞 ladybug ↑
📄 Specs ↑
This git repo has everything that exists in the open semio ecosystem 🤯
⚖️ Principles ↑
Let's start with the rule of thumbs that this codebase was built with 🫰
💾 If something can be written in a single file, then it probably should ✅
I know, the urge to tidy up or separate things is big 🗃️
But try to withstand it 🫥
Out of my experience, it makes development slower, not faster 🐌
A single file is easier for humans and computers to understand 💡
You will be supprised
- by the awesome fill-in-the-middle suggestions of your copilot 🤖
- by the hassle-free context selection for your ai agent 🖱️
- by the smooth refactor experience by just going top-to-bottom ⬇️
- by the beautiful diff for your next code review 🔍
- by the clean git-history when you try to find a certain change 🔁
📁 If a folder doesn't make your life dramatically easier, don't create it ❌
We all know this ./src/** folder that has made it into a lot of starters 🚀
Other than feeling cool about using hacky abbreviations, does it really help you to understand the project faster and work more efficient on it?
If your project contains hundreds of config file and other project folders at the root, maybe 🤔
But most likely not ❌
📑 If multiple people work longterm on the same part, then one file for each part should be created ⚙️
Trust me, it will make collaboration much easier 🔀
📦 If you don't need an interface because something is not likely to be extended soon, don't create it ❌
The main question is the interface productive or not?
The pay-off of abstraction happens in the future 🛣️
Every extension profits from a clean interface 🚀
Most things are not extended 🪨
If you change your architecture, just design proper interfaces for something concrete not something potential and reactor it ✍️
🤏 Repeating code is ok if it the repeated code is close in the source code ✅
We are past the time where we copy code for no reason 📃
Actually repeated code can improve the quality of your copilots suggestion 🤯
The main question is how can your application grow?
If a change requires exponentially more duplication then you'll probably have to fix it 🛠️
If not, then you are probably good 👌
🤨 Wait, no high-level advice and only plain numbers, files, folders or close line of codes?
In my understanding, rule-of-thumbs are most useful when they are concrete 🔨
Besides that I am sure you know about KISS (Keep-It-Simple-Stupid), DRY (Dont-Repeat-Yourself), YAGNI (You-Aren't-Gonna-Need-It), SoC (Seperation-of-Concerns), Avoid Premature Optimization, Law of Demeter, LCHC (Low-Coupling-High-Cohesion), SOLID (Single Responsibility (SR), Open/Closed (OC), Liskov’s Substitution (LS), Interface Segregation (IS), Dependency Inversion (DI)), …
But as always, the devil is in the details 😈
Even if 95% of the codebase follows those principles, there are good reasons for the other 5% ⚖️
🚩 Don't worry, you'll figure out the possiblites and make the right choice for the specific problems ✅
🧑💻 Development ↑
Different components need different tools 🧰
For a complete setup you need:
- Windows 10 or 11
- Visual Studio 2022 Community
- Rhino 8
- Python 3.13
- Poetry
- Node
If you do not have Python installed, I recommend to install it over the Microsoft Store 🏪
Afterwards you can install poetry with this Powershell command:
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -In the console you will see a warning that the poetry.exe is not installed in the requested location 📁
Then copy the actual path ...\AppData\Local\Packages\PythonSoftwareFoundation...\Roaming\pypoetry\venv\Scripts and add it to your environmental path variable ➕
Then you can build.ps1 in the Powershell and add your full path LOCAL_PATH\dotnet\Semio.Grasshopper\Debug\net48 to your GrasshopperDeveloperSettings ⚙️
If you have never executed local Powershell before then you have to first Set-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine📦 Components ↑
A component is a piece of software which is packaged independently 🏝️
The core which is shared in the semio JavaScript ecosystem 🥜
An electron-based desktop app primarly working for with local kits 💾
A Model Context Protocol-based assistant 🧰
📚 @semio/docs ↑
A playground for sketchpad 🎮
The core which is shared in the semio .NET ecosystem 🥜
🔗 Useful links:
A full-blown Grasshopper Plugin that has (almost) everything 💯
⚙️ @semio/engine ↑
🔗 Useful links:
A hidden fat-client which exposes shared functionality to other desktop uis 🤝
It takes care of:
- CRUDs (Create-Read-Update-Delete) for local kits 💾
- Client-Server communication
↔️
It offers two APIs to other clients:
- A simple REST OpenAPI 🥇
- A complex GraphQL Relay API 🥈
{} REST OpenAPI
If you go to http://127.0.0.1:2412/api/docs/ you find the Swagger UI:
Still a prototype ✏️
If you go to http://127.0.0.1:2412/graphql/ you find the GraphiQL UI:
🛍️ @semio/assets ↑
👋 Hello semio ↑
🫀 Metabolism ↑
💿 Ecosystems ↑
You might have noticed that the individual components can be closely related such as sketchpad, Grasshopper and engine but they are in totaly different folders 📂
The reason for this is that the monorepo is not disected according content but according technology stack ✂️
This is less intuitive but more tool-friendly and everything that is easier for our tools is less pain to develop 🧑💻
🟨 JavaScript ↑
🔗 Useful links:
Currently only engine but in the future it might grow and then the .venv will be centralized, …
🔗 Useful links:
💯 Brand ↑
✍️ Concept ↑
✅ Do ↑
- Visual is better than text 👀
- Compact ➡️ Less space ➡️ More information ➡️ Faster to understand 🚀
❌ Dont ↑
- Rounded corners ⬜
- Shadows 🌤️
- Multiple unicode directly after each other 🥇🥈🥉
🌈 Colors ↑
🥇 Primary ↑
🥈 Secondary ↑
🥉 Tertiary ↑
⚫ Dark ↑
⚪ Light ↑
🩶 Grey ↑
Are you curious how a 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and 11 colored gradient can come together for an invertible theme in a semantically meaningfull way? Well, here is how you achieve it with 33 colors 🤯
📄 Typography ↑
Note
Try to place notes either in the beginning or the end of a section
- Be consistent with your language ♻️
- When things are analogical use the same sentence structure for it 🔄
- One symbol after every sentance 💯
- One symbol at a time 🥇
- A symbol is preferably an emoji or otherwise unicode ⚖️
- 📝 One symbol to summarize a title
- 💡 One symbol to summatize a title description and one to think about in the end 🤔
.are forbidden ⛔- All components in
semio(sketchpad,studio, …) start with a small letter 🔡 - Did you know that
…is just one character?
Tip
In the end of a section you can give the curious reader a summarizing question to think about the consequences and a link to more resources 🤔
- Sans serif: Anta 🖨️
- Serif: Kelly Slab ✍️
- Monospaced: Shart Tech Mono 🖥️
- Emoji: Noto Emoji ⚫
👀 Visual elements ↑
- Sharp corners 📐
- Borders □
- Basic geometric shapes ⚪
