Introduction

This book is conceptual documentation for Graviola: a schema-driven semantic CRUD framework used across several projects while it matures. It is written for developers who are comfortable with architecture, integration, and data modeling—not for end users.

What you will find here

• Problem framing — why federated, multi-source, and evolving models strain conventional tooling (The shape of a federated application).
• What Graviola is today — JSON Schema as the runtime contract for the model, storage-agnostic backends, forms, tables, and declarative authority mapping (What Graviola is, Capabilities today).
• How it is structured — layers and read/write data flow (Architecture and data flow).
• Where it runs — representative deployment shapes (Deployment scenarios).
• Honest scope — non-goals and when not to reach for Graviola (Limits, fit, and evaluation).
• Where it is heading — architectural trajectory, clearly separated from production guarantees (Architectural trajectory).
• Generative tooling — why a small, reviewable schema remains a good contract when models can draft code and UI (Graviola in the age of generative tools).
• Authoring upstream of JSON Schema — optional build-time modeling (for example LinkML as an authoring source for schemas) that still emits the JSON Schema, UI schema, and mapping artifacts Graviola consumes at runtime.
• Shared vocabulary — terms and literature (Glossary, Further reading); frontier questions that span multiple terms live in Outlook and open questions.

What this book is not

• Not the full framework API or package-by-package reference (that lives in the monorepo and will grow in separate technical docs).
• Not a Storybook substitute: UI components and interactive examples belong in Storybook; this book points there when useful.
• Not a single customer narrative: examples are illustrative across domains (heritage, internal tools, offline-first, etc.).

How to read progressively

1. Start with The shape of a federated application if the problem is new.
2. Read What Graviola is and Capabilities today for the current product story.
3. Use Architecture and data flow as the map of layers and pipelines.
4. Treat Architectural trajectory, Graviola in the age of generative tools, Outlook and open questions, and the Glossary as deepening material—optional until you need precision on lenses, sync, trust, generative workflows, or vocabulary.
5. If authoring fragmentation (many files per model) matters to your team, read LinkML as an authoring source for schemas for a build-time pattern that leaves Graviola's runtime unchanged.

Canonical seed sources for this edition live under seed/ in the same repository; chapters here are the book-shaped rearrangement of that content.

See also

• Graviola framework monorepo — code, apps/testapp, packages under @graviola/*.
• Glossary — definitions and references in one place.
• Outlook and open questions — unresolved tensions at the design frontier.