Selkie is an AI-assisted diagramming tool for users who prefer declarative configuration over manual drawing. It uses Mermaid to define diagrams and AI to provide scaffolding during early stages. Selkie helps move from concept to structured output and supports sharing, versioning, and manual refinement.
I'd had the idea for some time and started by building an end-to-end prototype to see if the concept worked. Using my JavaScript full‑stack template cito-starter (Angular frontend, Node.js backend), I produced a working first version in a few hours; the backend handles the OpenAI API calls. See the first UI render below:
Figure: Screenshot of the first version.
The first version does the following:
Sends user input to the backend and to OpenAI's Responses API (beta).
The response (expected to be Mermaid syntax) is returned to the frontend.
The frontend renders the diagram using Mermaid.
Regarding the name "Selkie": it comes from "Mermaid". Wikipedia describes Selkies as "mythological creatures that can shapeshift between seal and human forms by removing or putting on their seal skin". In Finnish, "Selkeä" means "clear". One main function of a diagram is to make information clearer.
Working on all fronts: UI, code and concept
Second iteration is underway. I replaced the custom contentEditable editor with Monaco and added frontend tweaks to support a more iterative workflow. Current topics include:
The idea seems to be done by others, e.g. Mermaid Chart and some VSCode plugins. How to differentiate when moving forward?
Skinning and customising both Monaco and Mermaid is quite annoying. What is the easiest path forward to keep momentum on the actual idea?
Mermaid sizing is not easy to tame.
Diagram versions and interaction with the model? Would some Git-like cli work?
Below is the latest UI:
Figure: Working on second iteration.
Second version
I haven't focused on LLM improvements yet, but the main features work end-to-end. Diagrams are stored in a database. Editing works and development-time use can begin; the project can be tracked within the app. Some recent work included:
Improving Monaco setup
Added tabs for managing multiple diagrams
UI adjustments, e.g. styling, components, resizing panes…
Signal-based "diagram manager" for handling state related concerns and syncing to backend.
Export as png
Refactoring of frontend code
Below is the second-version UI:
Figure: Second iteration.
Refactoring of the end-to-end project is ongoing. Next steps are deployment to a VM for public access and starting the LLM-focused development phase. The third version's content will be shaped as the idea matures.
Second iteration got some minor adjustments before deploying to the public domain. The changes include:
Added proper theme switching logic.
Replaced raw Monaco with an Angular wrapper; managing service workers was tricky.
Added shortcuts for marking tasks done and for formatting Gantt lines.
Added quick view selection (split, diagram, editor) for smaller viewports.
On top of application changes I spent some time hardening the nginx configs and adjusting scripts for deployment.
Below is the deployed version in light and dark.
Figure: First deployed version (dark).Figure: First deployed version (light).
Third version
Third iteration is in progress. I'm refining the version for home and work notes; LLM improvements are still pending. Recent work includes:
Getting Monaco service workers to work in the Angular bundle.
Fixing style issues like height and sizing on viewport changes.
Fixing flicker in diagram rendering.
Refining mobile view.
Adjusting zoom and pan behavior.
Adding save-as-text for diagram code (backup).
Minor end-to-end refactoring.
Below is the ongoing third version of the UI:
Figure: Third iteration in progress.
The Selkie project itself is tracked with the Selkie. Next items on the project's Gantt looks like this:
Figure: Next steps.
The solution turned out to be helpful
I spent recent days working on YAML-based syntax to make note-taking more consistent, easier to parse, and to allow pre-computation before sending content to Mermaid.
Currently I have added support for the following:
Add notes as yaml that are rendered into pre-organised sections in Mermaid.
Task items support all Mermaid Gantt supported start and end dates, plus some contextually useful ones, e.g. "today", "end-of-day" and "tomorrow".
Task items support work-day counts with excluded days (weekends/holidays). This lets chained tasks update schedules correctly when edited. Estimations remain tricky, but this is useful.
Adjusting the direction
After using Selkie for a few months, I learned a few things:
Configuring Monaco inside Angular is painful; registering custom language syntax and formatters caused many issues.
For converting free text to diagrams, the note format must be separate from presentation. The source format should be intuitive and easy to author.
Visualising notes is helpful; the challenge is balancing structure and freedom so content is parseable but still useful.
Selkie's refined purpose is to offer different viewpoints on notes; this can be done with multiple renderers alongside Mermaid.
Deployment isn't required for my use; I mostly work with local files across machines.
The AI role shifted to the editor: tools like GitHub Copilot can generate Mermaid content.
Some adjustments
Drop Monaco: use a robus external editor (e.g. VSCode) for authoring. This avoids spending time fixing the in-app editor and simplifies the UI to a renderer.
Replace local state with server-side logic: watch the filesystem and trigger SSE on changes, then reload and re-render.
Future challenges
Decide how to package the application: Electron? Docker? Maybe no packaging at all: just running the local scripts?
Design, develop and refine UI
Work on new renderers, e.g. D3 renderer for more advanced Gantt.
Sunsetting Selkie
I decided to archive Selkie and stop working on it. The main reasons:
I want to prioritise more important work.
The benefits don't justify the maintenance effort alongside other note-taking conventions.
Most time went into setup and wiring rather than interaction design or the concept. Building the e2e PoC was interesting, but in the end it mattered little.
Here are the key learnings, in no particular order:
Gantt diagrams are very effective for communicating project state; they connect past and future clearly.
Note taking format has to be user-friendly first, parsing-friendly second.
Diagram generation is useful, but not a daily need. AI helps most with cleaning syntax and typos rather than doing the thinking.
Deploying a PoC to a VPS with a custom domain adds a lot of extra work.
Iterating PoCs with a backend and database helps validate delivery but greatly increases effort. Consider a local-first approach to move faster and learn more quickly.
Selkie can be archived as a proof of concept that did not deliver the expected usefulness.
