---
audience: developers
summary: How ScaiScribe models documents, themes, charts, ingestion, templates, auth,
  and quotas.
title: Concepts
path: concepts
status: published
---


# Concepts

Six ideas that explain why everything else works the way it does.

| | |
|---|---|
| [Spec format](/docs/scaiscribe/concepts/specs) | The JSON document that *is* your document. Everything else (DOCX, PPTX, XLSX, PDF) is a derived artefact. |
| [Themes](/docs/scaiscribe/concepts/themes) | One file that controls typography, palette, page geometry, components, and chart colours across all formats. |
| [Charts](/docs/scaiscribe/concepts/charts) | Dual-emission — native chart parts where the library supports them, ECharts SVG image fallback otherwise. |
| [Ingestion + fidelity](/docs/scaiscribe/concepts/ingestion) | Reading existing documents into the spec model, with honest reporting about what survived and what didn't. |
| [Templates](/docs/scaiscribe/concepts/templates) | Register a `.docx` with `{{ placeholders }}`, fill it with structured data. |
| [Auth + quotas](/docs/scaiscribe/concepts/auth-and-quotas) | How tenants authenticate, what limits apply, where to inspect usage. |

## Mental model in one paragraph

The **spec** is the canonical state — a JSON document describing what to render. ScaiScribe stores specs in its database and applies edits as PATCH operations against them. Binaries (`.docx`, `.pptx`, `.xlsx`, `.pdf`) are *derived* by feeding the spec + a **theme** through format-specific renderers. **Ingestion** runs the same process in reverse: it parses an uploaded binary into a spec, surfacing structural loss as fidelity warnings. The whole loop is byte-stable enough that ScaiScribe-authored documents round-trip equivalently via an embedded JSON breadcrumb at `scaiscribe/breadcrumbs.json` in the zip.

That's it. Pick any subsection and dive in.