Developer guide

SideDoc is a browser-based editor for datasheets: structured descriptions of cultural heritage datasets. A datasheet is a JSON document that follows a profile, a JSON Schema generated in a separate schemas repository. The editor renders a form from the profile, validates the document against it and exports it as HTML, Markdown, PDF or DCAT-AP JSON-LD.

There is no application server. All logic runs in the browser: the backend is a TypeScript library (@sidedoc/backend) that the Vue app bundles. A deployment is a set of static files, usually the container image described in the deployment guide.

This guide is for people who work on the code. Start with Getting started, then read Architecture.

Repositories

Repository	Contents
gitlab.com/sidedoc/sidedoc	This monorepo: backend library, Vue app, documentation site, container image.
gitlab.com/sidedoc/schemas	Profiles, type library, SKOS vocabularies, help texts, DCAT-AP mapping files, and the scripts that generate them from a Google Sheet.

Why they are split is recorded in ADR 0001.

Repository map

sidedoc/
├── package.json                npm workspaces root (build, typecheck, test, docs:*)
├── app/
│   ├── sidedoc-backend/        @sidedoc/backend, the headless library
│   │   ├── src/index.ts        public API (re-exports src/lib/index.ts)
│   │   ├── src/lib/domain/     contracts, entities, shadow model, schema utilities
│   │   ├── src/lib/application/ services, adapters, records, transformers, persistence
│   │   ├── src/lib/infrastructure/ IndexedDB storage
│   │   ├── src/lib/testing/    in-memory and mock services
│   │   ├── scripts/            build-time sync from the schemas repo
│   │   └── __tests__/          unit, integration and e2e tests (vitest)
│   └── sidedoc-frontend/       the Vue 3 app
│       ├── standalone.html     entry of the deployed editor (StandAlone.vue)
│       ├── index.html          entry of the backend demo app (App.vue, BackendDemo.vue)
│       ├── testbench.html      entry of the component testbench
│       ├── public/schemas/     committed copy of the published schemas
│       ├── public/vocab*/      committed copy of the SKOS vocabularies
│       ├── src/components/editor/ schema-driven form renderer
│       ├── src/standalone/     controller and helpers for the standalone editor
│       ├── src/config/         runtime config, schema version and profile resolution
│       ├── tests/              Playwright suites (accessibility, e2e, smoke)
│       └── doc/accessibility/  WCAG 2.2 evidence
├── docker/                     static container image (nginx) and entrypoint
└── docs/                       this VitePress site (docs.sidedoc.app)
    ├── typedoc.json            API reference generation
    └── dev/api/                generated, not committed

Where to go next

• Getting started: clone, build, run, test.
• Architecture: backend layers, active entities, data flow.
• Editor rendering: how a schema node becomes a Vue component.
• Exports and mappings: HTML, Markdown, PDF and DCAT-AP.
• Persistence: IndexedDB, Google Drive, S3 and local files.
• Testing: vitest and Playwright suites.
• Accessibility: WCAG 2.2 AA work and the merge gate.
• Contributing: branches, commits, code style, TSDoc.
• Decisions: architecture decision records.
• API reference: generated from the backend's TSDoc comments.