# Architecture

SWMS Builder is organized as a controlled document pipeline. The private implementation separates document production from review, validation, and recordkeeping so that every generated SWMS can be traced back to a known set of inputs and gates.

## System Shape

```mermaid
flowchart LR
  A["Job intake"] --> B["Source evidence"]
  B --> C["Risk and HRCW classification"]
  C --> D["Controlled generator"]
  D --> E["DOCX output"]
  E --> F["Post-process integrity step"]
  F --> G["Validator"]
  G --> H["Review packet"]
  H --> I["Verification agent"]
  H --> J["WHS review agent"]
  I --> K["Human release decision"]
  J --> K
  K --> L["Record copy"]
```

## Core Components

### Intake

The workflow starts with a structured intake: PCBU, site, principal contractor or contract administrator, responsible roles, trade scope, work method, issue date, jurisdiction, and known HRCW triggers. Unknowns are kept explicit rather than invented.

### Evidence Register

Source material is treated as evidence, not decoration. The private workflow records which sources support legal references, HRCW classification, major controls, supporting document prerequisites, and stop-work triggers.

### Controlled Generator

The private system uses a controlled generator and template approach to produce consistent SWMS structure. Job-specific configuration is separated from master behavior so new work can branch from a known generator version without changing the master.

### Post-Process Step

Generated DOCX files are post-processed before validation. This keeps the Word package structurally clean and prevents release of malformed document XML.

### Validator

Validators check issue-readiness. Typical checks include:

- unresolved placeholders;
- required project metadata;
- validation mode;
- HRCW selection and evidence source alignment;
- task sequencing;
- risk code presence and ordering;
- hold point and stop-work trigger structure;
- legal basis metadata;
- supporting document prerequisites.

### Review Packet

The review packet prepares a compact read-only bundle for review agents. It contains enough metadata for inspection without letting agents mutate the generated document.

### Agent Gates

Two read-only gates are used in the private workflow:

- Verification Agent: document integrity, placeholder, formatting, and mechanical consistency checks.
- WHS Review Agent: Australian construction WHS judgement, HRCW reasoning, and control adequacy checks.

Issue-ready documents do not proceed when either gate returns a blocker unless a dated human override is recorded.

## Anti-Hallucination And Anti-Slop Loop

The workflow does not treat generated text as evidence. It treats generated text as a candidate that must pass through gates before it can influence an issue-ready document.

![Anti-hallucination and anti-slop control loop](../assets/anti-hallucination-loop.svg)

The loop is built around four controls:

- unknowns are quarantined with explicit placeholders or conditional status;
- source evidence must support HRCW classification, legal basis, and major controls;
- validators reject missing metadata, unresolved placeholders, weak task logic, and release blockers;
- read-only review agents inspect the result without mutating the generated document.

If evidence is missing, the workflow routes the item back to intake rather than polishing a guess.

## Privacy Boundary

The public repository stops at architecture and synthetic examples. It does not include the private generator, validators, client records, generated outputs, source PDFs, logs, or deployment configuration.

The boundary is intentional: the value being demonstrated is the controlled workflow design, not the publication of private operational material.

## Future Public Options

Potential safe future additions could include:

- a minimal synthetic schema;
- a toy demo generator with fictional data only;
- example validator checks that do not reveal production logic;
- a static walkthrough video or anonymized diagram.

Those additions should be reviewed before publication.