audita/docs/internal/overview.md

Audita Internal Overview

Scope

This document owns the implemented component map. For normative boundaries, see architecture policy; for task-specific reading and baseline commands, see the contributor guide.

Package Map

Executable and command orchestration:

• cmd/audita: executable entry point.
• internal/cli: argument parsing, config commands, streams, filesystem wiring, and process orchestration.

Core deterministic components:

• internal/core/config
• internal/core/schema
• internal/core/normalization
• internal/core/chunking
• internal/core/outputschema
• internal/core/diagnostics
• internal/core/reporting
• internal/core/modulecatalog

Framework orchestration and contracts:

• internal/framework/contracts
• internal/framework/modules
• internal/framework/proposal_generation
• internal/framework/proposals
• internal/framework/runner
• internal/framework/validators
• internal/framework/llm
• internal/framework/responseschema
• internal/framework/structuredoutput
• internal/framework/processreport
• internal/framework/promptcontext
• internal/framework/stagename

Domain implementations:

• internal/modules/*
• internal/validators/*
• internal/prompts

Supporting areas:

• docs/: canonical documentation.
• examples/: maintained copyable inputs and configuration.

Current Scope

Runtime state is held in memory plus per-run diagnostics artifacts. Audita does not currently implement a plugin framework, generic workflow engine, resume/checkpoint/manifest system, remote storage, or multi-process service mode. Its provider adapter is OpenAI-compatible HTTP behind the structured LLM client contract. These are current implementation boundaries, not bans on future work.

Main Execution Path (audita process)

The CLI prepares input and configuration, invokes the runner, and writes results. The pipeline owns detailed state transitions; the operations guide owns the operator workflow and physical artifact lifecycle.

Component Responsibilities

Core components implement configuration defaults/loading/validation/redaction, transcript and glossary schemas, normalization and chunking, output encoding, diagnostics artifact helpers, and public report structures.

Framework components implement module and validator contracts, proposal generation and application, prompt context, runner orchestration, LLM scheduling and transport, response schemas, and process-report/correction-ledger assembly. Domain packages provide correction modules, built-in validator chains and execution metadata, and embedded prompt assets.

These describe the implementation; dependency and ownership requirements belong to the architecture policy.

Change Recipes

• Configuration, CLI, and example changes
• Module changes
• Validator changes
• Runtime orchestration changes: use pipeline, LLM runtime, or diagnostics/reporting and their test references.

Related Internal Docs

• docs/internal/pipeline.md
• docs/internal/modules.md
• docs/internal/validators.md
• docs/internal/llm-runtime.md
• docs/internal/diagnostics-reporting.md
• docs/internal/prompts.md
• docs/internal/output-schemas.md