154 lines
5.4 KiB
Markdown
154 lines
5.4 KiB
Markdown
# 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`
|