audita/docs/architecture/architecture.md

# Audita Architecture

## Scope
This document describes the production architecture implemented in this repository today.

Audita is a single-process Go CLI that:
- loads effective runtime configuration;
- reads transcript and glossary inputs;
- normalizes and sections transcripts;
- runs a built-in module pipeline with validator chains;
- writes transcript output and run diagnostics.

## Runtime entrypoints
Primary CLI commands:
- `audita process <transcript.json> --glossary <glossary.yaml> [flags]`
- `audita config validate --config <config.yml>`
- `audita config print-effective [--config <config.yml>]`

Command ownership lives in `internal/cli/run.go`.

## Configuration model
`internal/core/config` owns defaults, file parsing, environment overrides, CLI overrides, and validation.

Effective-config loading for `process` and `config print-effective` is centralized in:
- `ResolveConfigPath`
- `LoadEffectiveConfig`

Effective precedence for `audita process`:
1. defaults
2. config file
3. environment overrides
4. CLI overrides

`audita config validate` is intentionally file-only validation:
- load versioned file;
- apply onto defaults;
- validate;
- do not apply environment overrides.

Supported module and output-schema keys are validated through shared catalogs:
- module keys: `internal/core/modulecatalog`
- output schemas: `internal/core/outputschema`

## Pipeline and module orchestration
The built-in module sequence is configured in runtime config and executed by `internal/framework/runner` through resolved module specs.

Current default sequence:
- `glossary`
- `homophones`
- `glossary`
- `spoken_word`
- `grammar`

Execution behavior:
- modules execute serially over the working transcript;
- section proposal work can run concurrently within a module;
- validator execution happens on generated proposals before application;
- approved proposals are applied once per module in deterministic proposal-index order.

Production modules remain separate packages:
- `internal/modules/glossary`
- `internal/modules/homophones`
- `internal/modules/spoken_word`
- `internal/modules/grammar`

## Proposal generation and prompt context
Shared proposal plumbing is centralized in `internal/framework/proposal_generation`.

Module packages provide:
- module identity and replacement policy;
- module-specific prompt message building;
- built-in validator chain selection.

Shared prompt payload helpers are in `internal/framework/promptcontext`.

## Validator architecture
Built-in validator construction and chain composition live in `internal/validators`.

Shared validator runtime mechanics live in `internal/framework/validators`.

Execution class metadata (deterministic vs LLM-backed) is centralized in `internal/validators/metadata` and used for ordering and reporting classification.

## Structured LLM boundary
All production LLM calls go through the internal contract:
- `contracts.StructuredLLMClient`
- `CompleteStructured(ctx, req, out)`

The OpenAI-compatible HTTP adapter is implemented in `internal/framework/llm`.

Structured response schemas are registered in `internal/framework/responseschema` and attached to requests via `response_format` metadata.

Malformed structured-output detection is centralized in `internal/framework/structuredoutput` and reused by proposal generation and validator execution so downgrade behavior stays consistent.

## Stage naming and diagnostics metadata
Diagnostics stage naming is centralized in `internal/framework/stagename`:
- module proposal stage names;
- proposal-generation stage names;
- validator batch stage names.

Prompt metadata and response-schema metadata each expose canonical diagnostics maps via:
- `prompts.Metadata.DiagnosticsMap()`
- `responseschema.Schema.DiagnosticsMap()`

## Diagnostics and reporting
Run-directory artifacts are owned by `internal/core/diagnostics`.

Stable artifact names are centralized constants (for example transcript artifacts, `invocation.json`, `effective-config.json`, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, `error.log`).

Report diagnostics path metadata is constructed through `BuildDiagnosticsMetadata`, which keeps run-directory artifact references consistent between success and failure reports.

## Secret redaction
Redaction responsibilities are split by concern:
- structural config redaction: `config.Config.Redacted()`
- byte/string payload redaction for diagnostics and surfaced errors: framework redaction utilities.

Configured LLM secret extraction is centralized in `llm.ConfiguredSecrets(cfg)` and reused across proposal and validator diagnostics paths.

## Output contracts
Transcript output schema selection is owned by `internal/core/outputschema`.

Supported schemas:
- `bare-segments`
- `audita-v1`

Unknown schema keys fail validation and runtime resolution.

## Key package map
Core packages:
- `internal/core/config`
- `internal/core/schema`
- `internal/core/normalization`
- `internal/core/chunking`
- `internal/core/diagnostics`
- `internal/core/reporting`
- `internal/core/modulecatalog`
- `internal/core/outputschema`

Framework packages:
- `internal/framework/contracts`
- `internal/framework/proposals`
- `internal/framework/proposal_generation`
- `internal/framework/promptcontext`
- `internal/framework/runner`
- `internal/framework/validators`
- `internal/framework/llm`
- `internal/framework/responseschema`
- `internal/framework/stagename`
- `internal/framework/structuredoutput`

Domain packages:
- `internal/modules/*`
- `internal/validators/*`
- `internal/prompts`