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