audita/docs/internal/overview.md

Audita Internal Overview

Scope

This document is the internal architecture entry point for developers and coding agents.

It summarizes:

• package boundaries;
• the main process execution path;
• where to add new code safely.

Package Map

CLI and command orchestration:

• internal/cli

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

Main Execution Path (audita process)

High-level flow:

1. CLI loads effective config and validates CLI requirements.
2. Run directory is created and invocation/effective config artifacts are written.
3. Transcript/glossary files are loaded and parsed.
4. Transcript is normalized and chunked.
5. runner.Run executes configured module instances.
6. Proposals are validated, applied deterministically, and serialized in selected output schema.
7. Process report, utilization diagnostics, correction ledger, and retention decisions are finalized.

Boundary Summary

• internal/core/* owns deterministic, reusable logic and persistence-independent rules.
• internal/framework/* owns orchestration contracts and reusable runtime plumbing.
• internal/modules/* owns module-specific proposal behavior and prompt usage.
• internal/validators/* owns validator composition and built-in chain assembly.
• internal/prompts owns embedded prompt assets and metadata registry.

Where To Add New Code

Add config fields:

• internal/core/config

Add module behavior:

• one package under internal/modules/<module_key>
• registration/wiring through internal/framework/modules and config module list

Add validators:

• implementation under internal/validators/<validator_key>
• registry/chain wiring in internal/validators

Add runtime orchestration behavior:

• internal/framework/* (runner/proposal/validator/LLM plumbing)

Add CLI surface:

• internal/cli

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