I've always felt that there was a missing tool to do 'software design'.
There are obviously things like:
- ArchiMate
- C4
And of course, the litany of diagramming languages & tools:
- Excalidraw
- TLDraw
- LucidChart
- Mermaid
Then there are tons of word processings / markdown editors for documentation:
- Google Docs
- Word
- Notion
- Confluence
- Obsidian
- Apple Notes
- `.md` files in `./notes`
But none of these have the integrated, UX and flexibility to build out a "workspace".
> Obsidian probably does to be quite honest, but it's almost too flexible. (And lacking the metadata optionality needed)
What would an opinionated, but hackable (and LLM-parsable by default) domain model look like for a purpose-built tool designed for technical & solution architects?
#### Core Entities
| Entity | Project | Decision | Document | Risk | Link | Shared | Diagram |
| ----------------- | -------------------------------------------- | ---------------------------------------------- | -------------------------- | ------------------------------------ | ----------- | ------ | --------------------------- |
| **Contains** | Decisions, Documents, Diagrams, Links, Risks | | | | | ? | |
| **Relationships** | Depends On | Affects, Addresses, Supersedes, Illustrated By | Contextualizes, References | Affects, Mitigated By, Documented In | References? | ? | Illustrates, Contextualizes |
But this feels a bit too terse. Also very temporally oriented (projects "occur" at a point of time). Systems are the actual core grouping unit for architecture / software design.
Systems in their most abstract sense are persistent.
So maybe it's more like:
| Entity | System | Project | Decision | Risk | Diagram | Document | Link |
| ----------------- | ------------------- | ------------------- | ------------------ | -------- | ----------- | -------- | ---------- |
| **Has** | Artefacts, Projects | Artefacts | Artefact | Artefact | Artefact | Artefact | Artefact |
| **Relationships** | Depends On | Affects, Depends On | Affects, Addresses | Affects | Illustrates | Explains | References |
| Type | Abstract | Abstract | Abstract | Abstract | Concrete | Concrete | Concrete |
This still feels like it has some gaps. It mixes abstract concepts (systems, decisions, risks, projects), with concrete artefacts (diagrams, documents, links).
Perhaps that's the distinction needed:
- Concrete Artefact (Document, Diagram, Link)
- Abstract "Grouping" (System, Project, Decision, Risk)
Then, in words:
- Systems are persistent architectural entities.
- Systems can contain many artefacts.
- Represented as a JSON file.
- Projects are temporal entities.
- Projects can contain many artefacts,
- Projects can affect systems.
- Represented as a JSON file.
- Artefacts are polymorphic, concrete files.
- One of: Diagram, Document, Link
- Can be tagged with extensible tags.
- Can have relationships to other artefacts, or abstract groups.
- Relationships are polymorphic, concrete metadata.
- One of: Illustrates, Documents, Supersedes, [USER DEFINED]
- Relationships have many fields
- Tags are applied to individual artefacts to denote their context in a system or project
- Decisions and Risks are special artefact types.
- Have a status
- Risk: Has a SEV
- Has relationships
- Represented as a JSON file.
#### Hackable
To be hackable, and immediately valuable - you should be able to start using this tool _fast_, building complexity over time.
Also - because it's opinionated, it should come with some quick onboarding to set up your "Workspace".
- Choose a directory
- Choose a template (free form - no template, just artefacts, opinionated - fixed template of the above, flexible - template ^ of the above, but you can change it)
- Configurable Sync (Cloud, Git)
- "Create your first system"
Then we need some quick short cuts.
The nature of the work that these professionals might do is not always deep work.
It's meetings, quick conversations and ad-hoc sessions.
Ideally:
- You start with a quick note / diagram.
- You iterate or make rough drafts.
- You refine it out later, dividing it up and creating the required separation of concerns.
The agent should be _recommending_ how to do this.
#### Agent?
Why do we even need an agent here? At first - probably not that useful save for syntax fixing in diagrams-as-code.
Maybe rephrasing / writing assistance?
But over time:
- querying
- understanding dependencies
- with versioning / .git history - understand evolution?
#### Collaboration
I reckon anyone doing the job of "architecture" is rarely working in isolation.
What if you could have built-in relationships to systems, projects, and artefacts created by other people you're working with?
What if the agent could read through the relationship graph _across_ an organization?
Does that unlock anything valuable or "cool"?
#### Sub Systems
I think in a purist "strict mode", everything is a system. There can be no shared artefact that doesn't comprise part of a system. In fact, systems can contain systems if necessary.
Subsystems conceptually exist.
#### JSON-config-everything vs SQLite
Ideally, I want the full configuration for each "workspace" to be as portable as possible, but without needing to depend on a third-party hosting provider.
In JSON, this could look like:
> {tool_name} in the below example is just because I haven't figured out what to call this thing.
```
/my-workspace-name.{tool_name}.json
{
workspaceName: ...,
projects: [project-name.{tool_name}.json],
systems: [system-name.{tool_name}.json],
customGroups: [custom-group-a.{tool_name}.json]
}
```
Then because all these abstract groups are roughly the same:
```
/custom-group-a.{tool_name}.json
{
artefacts: [{PATH_TO_ARTEFACT_CONFIG}]
}
```
```
/{PATH_TO_ARTEFACT_CONFIG}
{
raw_file: [], // literally the .md, .excalidraw, .mmd, .puml file (in the case of links it'll be {id}.link.txt - hidden in IDE view)
metadata_file: // has the relationships & other md
}
```