narratio/docs/internal/overview.md

Internal Overview

This document is the implemented component map for Narratio. Normative system boundaries and dependency direction belong in Architecture. User and operator contracts belong in the CLI, Configuration, Operations, and Troubleshooting. Externally observable tool and format contracts belong under Integrations.

Execution Path

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	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.

Pipeline Stage Set

The implemented canonical order is:

1. prepare
2. transcribe
3. merge
4. polish
5. normalize
6. trim
7. extract
8. render
9. analyze
10. publish
11. notify (placeholder)

notify currently has optional notifier call behavior and no persisted pipeline outputs; its default collaborator is a no-op sender. The focused stage documents own implementation mechanics. The CLI and Operations own user-visible invocation and execution semantics.

Focused Documentation

• Adapter Internals: external adapter boundaries, composition, failure behavior, and test surfaces.
• Artifact Internals: source identities, runtime catalog, resolution, previous requirements, and current-state helpers.
• Manifest Internals: session and run records, persistence, and execution transitions.
• Storage Internals: object-store interface and S3 behavior.
• Workspace Internals: local layout, locking, and cleanup guardrails.
• Restore Internals: discovery, planning, execution, and reporting.
• prepare
• transcribe
• merge
• polish
• normalize
• trim
• extract
• render
• analyze
• publish

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.