Diagram-to-code app with a rules engine

---

✦ Why Solarch?

Most AI tools generate code and hope the architecture catches up. Solarch flips that.

It generates architecture first, grounded in a library of canonical patterns, validated by a strict Rules Engine, and refined through a self-correcting loop. The AI proposes, the rules verify, and only valid graphs land on the canvas.

• One canvas for the whole system: 21 node families (controllers, services, repositories, tables, DTOs, queues) and the 16 semantic edges between them.
• AI Architect grounded in GraphRAG: an agentic LLM pipeline pulls from a vector-indexed pattern library, so it never plans from a blank context. Everything it proposes must pass the rules gate before it lands.
• Rules Engine as a hard gate: 40 whitelist rules, 7 anti-patterns, 3 conditional checks. Frontends can't talk to tables, and controllers can't reach repositories.
• Self-correcting loop: rules rejections feed back into the agent; the AI revises until the graph is clean, or the request ends without a commit.
• Diagram → NestJS code: deterministic codegen scaffold from the graph, plus optional Surgical AI for method bodies.
• Four surfaces, one project: Canvas, Code, API, and Docs, switched from the top bar without losing context.
• Live Instruct Mode: Switch modes and chat with your design. Every answer cites the exact nodes; chips focus the canvas in real time.
• Single-home + reference tabs: Each node lives in one tab. Other tabs import it as a reference, not a copy. One source of truth, multiple views.
• Type-safe from DB to button: Zod schemas at the backend, OpenAPI in the middle, openapi-fetch on the frontend. The API contract is a compile-time check.

---

✦ Gallery

1. Start with a prompt Type what you want to build. The AI Architect kicks in: pulls canonical patterns, plans the graph, and applies it through the Rules Engine.	2. Sketch → architecture (preview) Freeform sketch becomes a structured graph on Refine. Native sketch surface on the roadmap; the AI-driven refine path runs today.
3. Watch it build itself Nodes pop in with zen animations, edges flow with the right semantics. Every relationship is rule-validated before it commits.	4. Pattern library (preview) A standalone constructor library is on the roadmap. The same canonical patterns already power GraphRAG behind the scenes today.
5. Connect anything, legally Hover a port, drag, snap. The Rules Engine rejects illegal connections instantly. Semantic edges carry meaning, not generic arrows.	6. Every node, purpose-built editor Double-click any node. Column grids for tables, method tables for services, endpoint rows for controllers. No generic JSON forms.

---

✦ Features

AI & Rules AI Architect: agentic LLM loop with atomic tool calling Rules Engine: 40 whitelist · 7 blacklist (ERR_001..007) · 3 conditional GraphRAG: vector search over a canonical pattern library Self-correction loop: rejection feeds back into agent state, AI revises Vector-native Neo4j: embeddings + graph in one DB, no extra Pinecone Local embeddings: compact multilingual sentence-transformer, on-box, 384-d 21 node families: Table, DTO, Model, Service, Worker, Controller, Repository, Cache, Middleware, and more 16 semantic edges: CALLS, QUERIES, WRITES, PUBLISHES, SUBSCRIBES, THROWS... NestJS codegen: deterministic scaffold + optional Surgical AI fill

Workspace & UI Custom Canvas 2D: 60fps, dual-canvas, viewport culling, devicePixelRatio AI Omni-Bar: Agent (build) + Instruct (Q&A) modes, SSE streaming Live node chips: citations focus the canvas with a soft halo Purpose-built inspectors: per-type editors (4 today, the rest on roadmap) Multi-tab workspace: single-home model + cross-tab references, not copies Edge bundling & routing: obstacle-aware bezier and elbow paths Type-safe API client: Zod → OpenAPI → openapi-fetch + openapi-typescript Light Blueprint design: warm paper, semantic family colors, hairline grid, Satoshi + JetBrains Mono Bring-your-own-key: OpenAI, Anthropic, Ollama, DeepSeek, and more. Your server, your quota

---

✦ The Philosophy

Solarch doesn't ask the AI to be honest. It puts a deterministic gate between the AI and your architecture.

The industry has spent two years asking LLMs to write code, and the result is confident hallucinations: ghost APIs, phantom tables, codebases that compile but lie. Solarch attacks the structural half of that problem. Architectural relationships (a controller calls a service, a service queries a repository) are either present in the graph or they are not, so they can be checked deterministically instead of trusted.

Three layers work together:

1. GraphRAG. The agent starts every request by retrieving canonical patterns from a vector-indexed library, so it never plans from a blank context.
2. Rules Engine. Every mutation passes a deterministic gate of 40 whitelist rules, 7 anti-patterns, and 3 conditional checks. Illegal edges never land, and the schema can't be coerced.
3. Self-correction loop. When the Rules Engine rejects a draft, the violation message feeds back into the agent state. The AI revises until the graph is clean, or the request terminates without a commit.

The result: no API in the generated code that isn't in the diagram, and no edge in the diagram that breaks the rules.

What the Rules Engine does NOT guarantee

The gate is structural, not semantic. Method bodies are LLM-written (the optional Surgical AI fill), gated by compiling the output with tsc and running tests in a verify loop, and marked unverified when that gate is skipped. The Rules Engine guarantees the shape of your architecture; it does not prove your business logic is correct.

Every number in this README is countable in the source: the 40 whitelist rules and 7 blacklist codes live in apps/server/src/rules/registry. Count them yourself.

---

✦ Try it

Don't want to clone, configure, or run Docker? Use the hosted product:

	Link	What you get
App	app.solarch.dev	Full canvas: sign up and build in the browser. Always up to date.
Website	solarch.dev	Product overview, demos, updates.

Zero local setup.

---

✦ Self-Hosting

Want the stack on your machine, with your LLM key and your data? This repository is the complete source-available self-host edition: NestJS backend, canvas UI, vector-native Neo4j, local embeddings.

git clone https://github.com/solarch-dev/solarch.git
cd solarch
./install.sh          # Linux/macOS: Neo4j password + AI provider wizard
docker compose up --build
# → http://localhost:3000

No login screen. Bring your own LLM API key. By default Docker binds to 127.0.0.1 only.

Windows: ./install.ps1, then the same docker compose command.

Need	Details
Docker + Compose v2	Required
LLM provider	Tool-calling model, see AI providers
LAN / VPS	Enable HTTP Basic Auth (Self-hosting guide)

Hosted alternative: app.solarch.dev · solarch.dev

---

✦ Documentation

Full guides live in docs/:

Guide	Topics
Getting started	First run, four surfaces, API keys
Canvas & Rules Engine	Nodes, edges, error codes
AI Architect	Agent, Instruct, GraphRAG
Codegen	NestJS scaffold, Surgical AI
CLI & API keys	solarch login, MCP
Self-hosting	Env, security, rate limits
Development	pnpm dev, tests
Deployment	Caddy, systemd, production

CLI / MCP / VS Code extension: solarch-tools.

---

✦ FAQ

Is this open source? Strictly, no. PolyForm Noncommercial is a source-available license, not OSI-approved. It is free for personal use, research, education, and nonprofits. Commercial use needs a license: info@solidea.tech.

Isn't this just MDA / Rational Rose again? MDA generated the scaffold and left you the hard 20%, and the diagram and code drifted by sprint 3. Here the LLM handles that 20% behind tsc/test gates, drift detection is built in, and the graph is a live Neo4j source of truth, not a dead UML file. Structurizr stops at visualization; v0 stops at the frontend.

Do you build Solarch with AI tools? Yes. That's exactly why it exists: we needed a rules gate between the AI and the architecture ourselves first.

How is it tested? The rules engine and codegen pipeline carry 800+ server tests, including a gate that compiles generated output with tsc. Frontend test coverage is early; contributions welcome.

---

✦ Get Involved

We welcome feedback, discussions, and contributions.

• 💬 GitHub Discussions — Feature requests, design feedback, questions.
• 🐛 Issues — Bug reports, regressions.
• 🛠️ Contributing Guide — Local setup, conventions, commit style.

✦ License

PolyForm Noncommercial License 1.0.0 — © 2025–2026 Ugur Akdogan.

Free for personal use, research, education, and non-profit organizations. The source is available: fork, learn, modify, and share for any noncommercial use.
Commercial use requires a separate license. Reach out at info@solidea.tech.