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; optional debug artifacts are retained only when requested. Audita does not currently implement a plugin framework, generic workflow engine, resume/checkpoint/manifest system, remote storage, or multi-process service mode. Its role-bound PromptKit adapter implements the structured LLM client contract. These are current implementation boundaries, not bans on future work.

Main Execution Path (audita process)

The CLI inspects configuration and profiles, preflights and initializes active outputs, optionally creates debug evidence, invokes the runner, and finalizes transcript and reports. 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, PromptKit execution and observation mapping, 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