audita/docs/policy/architecture.md

Architecture Policy

Base Policy Version: 1.0

Last Updated: 2026-09-24

Purpose and System Shape

Audita is a single-process Go CLI for transcript polishing. Its architecture separates deterministic transcript processing from external LLM effects through narrow contracts and adapters. Correction modules and validators remain explicit, composable components in an ordered processing pipeline.

This policy owns architectural requirements. The internal overview owns the implemented component inventory and links to runtime mechanics. CLI, configuration, operations, and integration documentation own external contracts.

Ownership and Dependency Direction

• Core: owns domain data handling and reusable configuration, schema, normalization, chunking, output, diagnostics, and reporting contracts. Domain behavior must not require CLI or provider-transport knowledge.
• Framework: owns orchestration contracts and shared runtime mechanics for modules, validators, proposals, LLM adapters, and report assembly. It composes domain operations through explicit inputs and outputs.
• Modules: own narrowly scoped correction behavior and module-specific prompt choices. Keep module packages separate rather than collapsing their distinct responsibilities into a broad generic stage abstraction.
• Validators: own validation behavior and composition. Deterministic and LLM-backed validators remain explicit, independently composable elements.
• Prompts: own embedded prompt assets and metadata used by the runtime.
• CLI and adapters: own command parsing, streams, filesystem wiring, and transport. Keep these concerns outside module, validator, and schema logic.

LLM transport belongs behind StructuredLLMClient and framework adapter boundaries. Prefer small shared helpers over broad rewrites. Keep module and validator inputs, outputs, and configuration dependencies explicit, without hidden global state.

Correction and Concurrency Invariants

• Treat LLM responses as nondeterministic inputs. Preserve deterministic proposal indexing, validator ordering, transcript mutation, reports, and serialization.
• Validate corrections before final mutation, including local proposal checks, decision cardinality, and apply-time safety. Provider-side schema enforcement does not replace these checks.
• Keep LLM concurrency bounded and context-aware through PromptKit's engine-local per-backend admission. Proposal and validation calls selecting the same backend share that capacity, including retries and repairs. Preserve deterministic collection order. Recoverable model-operation failures stay local to their proposal response or validation batch; fatal invariant/application failure and parent cancellation stop peers and join them.
• Keep module and validator identities, reason codes, and execution-class distinctions stable where exposed as contracts.

The pipeline, modules, validators, and LLM runtime describe how these requirements are implemented.

State and Compatibility

Keep transcript mutation and output handling deterministic around external calls. Reports and correction ledgers are derived from processing results. Preserve the separation between transient processing state and filesystem adapters; physical report placement and optional debug retention belong to operations.

Public CLI, configuration, output-schema, diagnostics, report, prompt, module, and validator contracts should remain stable unless a change is deliberate and tested. The resilience work intentionally replaced the earlier JSON process report with versioned errors/recoveries YAML and a fixed Markdown overview; future changes should treat those current contracts deliberately. Current implementation limits are documented in the internal overview; they are not additional prohibitions on future development.

Errors and Secret Handling

Errors should identify the failed processing phase sufficiently for users and subprocess callers. Preserve the stream and exit behavior defined by the CLI contract and the artifact handling defined by operations.

Diagnostics, reports, and surfaced errors must not leak configured LLM secrets. Configuration redaction and LLM payload/error redaction have separate responsibilities and should remain separate. Implementation details belong in diagnostics and reporting.

Dependencies

Keep Audita dependency-light and prefer the Go standard library for CLI parsing, filesystems, synchronization, and tests. ConfigKit owns configuration loading, presence, provenance, and secret resolution; PromptKit owns prompt/profile loading, OpenAI-compatible transport, retries, repairs, and backend admission. Audita owns domain meaning, role selection, and deterministic processing.

Do not introduce broad CLI, dependency-injection, workflow, logging, or plugin frameworks without a concrete implemented need and focused tests.

Testing and Documentation

Follow the testing policy for risk-based sufficiency and stable test boundaries. Keep tests close to the behavior they protect; shared helpers should remove duplication without obscuring component-specific behavior. Relevant internal docs identify component tests and change recipes; the contributor guide provides baseline validation commands.

Follow the documentation policy for ownership, current versus future behavior, and the ADR lifecycle. Keep architecture concise and normative; use the roadmap for implementation plans rather than maintaining a changelog or future-feature specification here.