Mosaic
One model, many lenses.
Mosaic is a small compiler that turns a declarative description of a piece of software — a tessera — into the software around it: a REST server, a gRPC service, a typed CLI client, an MCP server, a terminal UI, a web app, an OpenAPI document, and the deployment artifacts for it. The tessera is the unit; the mosaic is what you get.
Design goals
- One source language for every concern — model, behavior, bridges, and lifecycle are all projections of the same tessera.
- Zero-cost abstractions — the generated code is plain, auditable, and dependency-light.
- Every design decision pinned to an executable proof — behavior is guarded by goldens and conformance checks, not vibes.
Where to start
- The Laws — the invariants the whole system holds to.
- AI — the assistant, voice, knowledge (Graph-RAG), and MCP surfaces that every app gets.
- Thesis Library — a worked end-to-end example: indexing a book library as a typed-entity knowledge graph.
- Reimplementation Playbook — drive an agent to re-implement an app from the generated MCP tools alone.
- ADRs — every design decision, 0001 → 0047.
The lenses
A single tessera renders, deterministically, into all of these:
| Lens | What it emits |
|---|---|
| REST | an axum server + authz on every route |
| gRPC | a typed service from the same commands |
| CLI | a typed client (the CLI is a client, not a twin) |
| MCP | an app MCP server (every exposed command) + a knowledge MCP server |
| Web | a Leptos / static-HTML app (use-case-first nav) |
| Terminal UI | a TUI over the same commands |
| OpenAPI | a spec document (also a proxy + knowledge source) |
| Site / Docs | a Zola static site + doc projections (pages, handbook, slides) |
| Deploy | workflow-shaped manifests (k8s / on-prem), deployments are data |
Self-contained handbook
This site has a single-file, print-ready companion: handbook.html — every ADR and guide in one document with a table of contents, generated at build time.
Publishing
This site is a Zola SSG project under docs-site/.
.github/workflows/mosaic-docs.yml
runs docs-site/tools/build_docs.py (injects title front-matter from each page's
H1 and generates the nav) + zola build, then publishes to
https://eugeis.github.io/mosaic/. docs/ stays the single source of truth.