60 lines
4.1 KiB
Markdown
60 lines
4.1 KiB
Markdown
# Internal Overview
|
|
|
|
This document is the implemented component map for Notarius. Normative
|
|
boundaries and dependency direction belong in
|
|
[Architecture](../policy/architecture.md). User and operator contracts belong
|
|
in the [CLI](../cli.md), [Configuration](../config.md),
|
|
[Operations](../operations.md), and [integration contracts](../integrations/).
|
|
|
|
## Execution Path
|
|
|
|
~~~
|
|
cmd/notarius -> internal/cli -> configuration and production composition
|
|
-> internal/framework/pipeline -> logical output files
|
|
-> internal/cli -> durable output and optional state/debug data
|
|
~~~
|
|
|
|
The CLI is the application boundary: it discovers configuration, composes
|
|
production registries and runtime collaborators, invokes the framework, and
|
|
places returned files. The framework resolves and prepares a fixed extraction
|
|
pipeline, then returns logical results without owning process behavior or
|
|
physical state roots.
|
|
|
|
## Components
|
|
|
|
| Area | Implemented owners | Responsibility |
|
|
| --- | --- | --- |
|
|
| Executable and command boundary | **cmd/notarius**, **internal/cli** | Process entry, command dispatch, configuration discovery, production composition, runtime collaborator setup, durable file placement, and user-facing reporting. |
|
|
| Configuration | **internal/core/config** | Defaults, strict YAML parsing, environment overrides, structural validation, effective resolution, redaction, and resolved-composition summaries. |
|
|
| Generic models | **internal/core/source**, **internal/core/artifacts**, **internal/framework/contracts** | Source documents and chunks, manifests and provenance, plus typed artifact, reference, validation, output, and structured-completion contracts. |
|
|
| Pipeline framework | **internal/framework/pipeline** | Registries, profile and reference resolution, typed preparation, validation, retry coordination, ordered execution, handoff, and result assembly. |
|
|
| LLM and prompt runtime | **internal/framework/llm**, **internal/framework/promptfs** | Provider-neutral structured completions, scheduling, profile recording, prompt assets, schema registration, and credential-shaped-value redaction. |
|
|
| Embedded LLM content | **assets** | Read-only centralized LLM-facing content, scoped by its consuming package; see [LLM Runtime](llm.md#prompt-and-schema-assets) and [D&D Module Internals](dnd.md#prompt-construction). |
|
|
| Runtime state | **internal/core/fileio**, **internal/core/debugbundle**, **internal/framework/checkpoint**, **internal/framework/chunkplan**, **internal/framework/chunkmap**, **internal/framework/debug** | Confined atomic files, debug bundles, checkpoint and chunk-plan state, accepted chunk maps, and pipeline-facing debug recording. |
|
|
| Production extensions | **internal/modules/generic**, **internal/modules/seriatim**, **internal/modules/dnd** | Domain-neutral extensions, Seriatim input support, and D&D extraction families registered into the production catalog. |
|
|
|
|
Generic core and framework packages do not depend on production extensions.
|
|
Concrete extensions depend inward on their contracts and are registered only at
|
|
the CLI composition boundary.
|
|
|
|
## Focused Documentation
|
|
|
|
- [Configuration Internals](configuration.md): loading, validation, effective
|
|
resolution, redaction, and resolved-composition identity.
|
|
- [CLI Internals](cli.md): command dispatch, production composition, run
|
|
orchestration, and terminal reporting.
|
|
- [Pipeline Internals](pipeline.md): resolution, preparation, execution,
|
|
validation, typed handoff, and framework state hooks.
|
|
- [Run State Internals](state.md): output, cache, debug collaborator
|
|
composition, and path safety.
|
|
- [LLM Runtime](llm.md): structured completion, scheduling, prompt assets,
|
|
profiles, and secret handling.
|
|
- [Module Internals](modules.md): generic extension registration, module
|
|
construction, validation, and reference mechanics.
|
|
- [D&D Module Internals](dnd.md): shared D&D extractor conventions, generated
|
|
reference projections, and lane-specific exceptions. Durable D&D and
|
|
Seriatim data shapes remain in the [integration contracts](../integrations/).
|
|
|
|
Use this map to find an owner, then read the focused document and its tests
|
|
before changing behavior.
|