# 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`](pipeline.md)
- [`docs/internal/modules.md`](modules.md)
- [`docs/internal/validators.md`](validators.md)
- [`docs/internal/llm-runtime.md`](llm-runtime.md)
- [`docs/internal/diagnostics-reporting.md`](diagnostics-reporting.md)
- [`docs/internal/prompts.md`](prompts.md)
- [`docs/internal/output-schemas.md`](output-schemas.md)