3.9 KiB
Development
This is the first-read landing page for people and LLM coding agents working on Notarius. It provides a concise repository orientation and routes each kind of change to its canonical documentation.
Orientation
Notarius is a small Go application for extracting structured data from source material. It is a general extraction platform with an initial Seriatim and D&D implementation. Configured modules run through a fixed workflow:
input -> chunk -> extract -> merge -> normalize -> output
The CLI is the application boundary. Core packages own deterministic models and policy, framework packages own reusable contracts and orchestration, and module and validator packages own concrete behavior.
Repository Map
cmd/notarius: executable entry point.internal/cli: CLI behavior and production composition.internal/core: deterministic source, config, artifact, diagnostics, and workspace packages.internal/framework: contracts, pipeline orchestration, validation helpers, checkpoints, debug recording, and LLM runtime plumbing.internal/modules: concrete implementations of the six pipeline stages.internal/validators: concrete output validators.docs: canonical policy, reference, integration, internal, ADR, and roadmap documentation.examples: maintained, secret-free example inputs and configuration.
See Internal Overview for the implemented component map and links to focused internal documentation.
What To Read
| When working on | Read | Why |
|---|---|---|
| Application shape, package boundaries, contracts, dependency direction, runtime guarantees, or safety properties | Architecture and relevant ADRs | Architecture defines the intended system and its invariants; ADRs preserve significant decision rationale. |
| Any documentation addition or revision | Documentation Policy | It defines canonical homes, audiences, current-behavior rules, and maintenance requirements. |
| Pipeline resolution or execution | Pipeline Internals | It documents profiles, references, validation, retries, checkpoints, and runner behavior. |
| Production modules or validators | Module Internals | It documents implemented module contracts, capabilities, assets, and registration. |
| LLM clients, prompts, schemas, profiles, or scheduling | LLM Runtime | It documents the transport boundary and Scriptorium integration. |
| Diagnostics, workspace state, resume, or debug artifacts | Diagnostics Internals, Operations, and Configuration | These separate implementation details, operator behavior, and configuration contracts. |
| CLI or user-visible configuration behavior | CLI Reference and Configuration | These are the canonical user and operator references. |
| External input formats, artifact schemas, or durable output files | Integration Contracts | Integration documents define external and durable data contracts. |
| Proposed or unimplemented behavior | Roadmap | Future work belongs only in roadmap documentation until implemented. |
For an existing subsystem, also inspect its focused tests and the package-local types and contracts before changing behavior.
Validation
Use focused package tests while iterating. Run the repository-wide checks when a change affects shared contracts, application behavior, or maintained documentation examples:
go test ./...
go vet ./...
go build ./cmd/notarius
Universal Reminders
- Keep non-roadmap documentation limited to implemented behavior.
- Update affected documentation and maintained examples in the same change as behavior.
- Use fakes, fixtures, or local test servers instead of real external services in tests.
- Do not expose secrets in code, errors, logs, diagnostics, manifests, documentation, or examples.