99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
# Internal Overview
|
|
|
|
This document is the implemented component map for Narratio. Normative system
|
|
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 [Troubleshooting](../troubleshooting.md).
|
|
Externally observable tool and format contracts belong under
|
|
[Integrations](../integrations/).
|
|
|
|
## Execution Path
|
|
|
|
```text
|
|
cmd/narratio -> internal/app -> configuration and production composition
|
|
-> internal/stage -> adapters and external systems
|
|
-> manifests and artifact resolution -> durable local/remote output
|
|
```
|
|
|
|
The executable delegates process behavior to the application boundary. The
|
|
application resolves configuration, composes concrete collaborators, acquires
|
|
session safety controls, and runs commands. Pipeline commands execute the
|
|
canonical stage sequence through adapter interfaces, while manifests record
|
|
progress and artifact services resolve durable inputs and outputs.
|
|
|
|
## Components
|
|
|
|
| Area | Implemented owners | Responsibility |
|
|
| --- | --- | --- |
|
|
| Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
|
|
| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, cleanup gates, and user-facing reporting. |
|
|
| Configuration | `internal/config` | Strict YAML loading, discovery, defaults, normalization, session templating, and validation. |
|
|
| Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
|
|
| External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
|
|
| Manifests | `internal/manifest` | Durable session progress, invocation audit state, stage transitions, validation, and atomic persistence. |
|
|
| Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. |
|
|
| Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
|
|
| Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
|
|
| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus durable single-file replacement helpers; unsupported directory syncing is reported explicitly. |
|
|
| Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
|
|
|
|
The application boundary composes concrete implementations. Stages depend on
|
|
Narratio-level contracts; external transport and SDK details remain in
|
|
adapters. The normative rules for these relationships remain in
|
|
[Architecture](../policy/architecture.md).
|
|
|
|
## Pipeline Stage Set
|
|
|
|
The implemented canonical order is:
|
|
|
|
1. [`prepare`](stage-prepare.md)
|
|
2. [`transcribe`](stage-transcribe.md)
|
|
3. [`merge`](stage-merge.md)
|
|
4. [`polish`](stage-polish.md)
|
|
5. [`normalize`](stage-normalize.md)
|
|
6. [`trim`](stage-trim.md)
|
|
7. [`extract`](stage-extract.md)
|
|
8. [`render`](stage-render.md)
|
|
9. [`analyze`](stage-analyze.md)
|
|
10. [`publish`](stage-publish.md)
|
|
11. `notify` (no-op)
|
|
|
|
`notify` currently has no persisted pipeline outputs and uses the explicit
|
|
`noop` notification mode. The focused stage documents own implementation
|
|
mechanics. The
|
|
[CLI](../cli.md) and [Operations](../operations.md) own user-visible invocation
|
|
and execution semantics.
|
|
|
|
## Focused Documentation
|
|
|
|
- [Adapter Internals](adapters.md): external adapter boundaries, composition,
|
|
failure behavior, and test surfaces.
|
|
- [Artifact Internals](artifacts.md): source identities, runtime catalog,
|
|
resolution, previous requirements, and current-state helpers.
|
|
- [Manifest Internals](manifest.md): session and run records, persistence, and
|
|
execution transitions.
|
|
- [Storage Internals](storage.md): object-store interface and S3 behavior.
|
|
- [Workspace Internals](workspace.md): local layout, locking, and cleanup
|
|
guardrails.
|
|
- [Restore Internals](command-restore.md): discovery, planning, execution, and
|
|
reporting.
|
|
- [`prepare`](stage-prepare.md)
|
|
- [`transcribe`](stage-transcribe.md)
|
|
- [`merge`](stage-merge.md)
|
|
- [`polish`](stage-polish.md)
|
|
- [`normalize`](stage-normalize.md)
|
|
- [`trim`](stage-trim.md)
|
|
- [`extract`](stage-extract.md)
|
|
- [`render`](stage-render.md)
|
|
- [`analyze`](stage-analyze.md)
|
|
- [`publish`](stage-publish.md)
|
|
|
|
Use this map to find an owner, then read its focused documentation and tests
|
|
before changing behavior.
|
|
|
|
The stage registry is implemented in `internal/stage/placeholders.go` and its
|
|
ordering is protected by `internal/app/planner_test.go`. Cross-invocation skip,
|
|
force, failure, and invalidation behavior is exercised in
|
|
`internal/app/runner_test.go` and `internal/app/run_stage_test.go`.
|