# Architecture

## Trust boundary

The source document, rendered pages, OCR tokens, and review state remain inside one local application process in v0.2. No connector, website, analytics SDK, crash upload, or cloud model is part of the processing path.

## Pipeline

```text
Untrusted local file
  -> type/size/page validation
  -> isolated PDF or image decode
  -> rendered RGB pages
  -> native text extraction (PDF only)
  -> local OCR on every page
  -> rule and context detectors
  -> local barcode detector
  -> deduplicated page findings
  -> human review and manual masks
  -> fresh raster-only PDF
  -> strict object inspection
  -> second render + OCR + barcode scan
  -> atomic release + log-safe report
```

## Modules

- `loader.py`: file limits, PDF/image decoding, rendering, native token coordinates
- `ocr.py`: Tesseract subprocess over stdin; no page-image temp file
- `detectors.py`: rule, context, coordinate mapping, and deduplication
- `barcodes.py`: local barcode position detection; decoded contents are not exported
- `analyzer.py`: capability gate and per-page risk warnings
- `gui.py`: review state, manual masks, and page confirmation
- `sanitizer.py`: opaque pixel redaction and fresh PDF reconstruction
- `verifier.py`: structural and residual-content verification
- `workflow.py`: atomic release, source-integrity check, and log-safe report
- `cli.py`: diagnostics, log-safe analysis, and verification
- `legal.py`: versioned NPO NT copyright, AGPL, Corresponding Source, no-warranty, and patient-data boundary notice

## Raster-only decision

Version 0.2 intentionally discards source vector text and source OCR layers. This lowers the risk of recoverable redacted content but increases file size, removes searchability and accessibility, and invalidates source signatures. A searchable output may be considered only after a separately validated clean OCR-layer builder exists.

## Open-source distribution boundary

The local application is licensed `AGPL-3.0-only`, with copyright held by NPO NT. Software source, build scripts, licence material, and notices are distributable; patient documents, medical datasets, credentials, keys, tokens, and production configuration are not source artifacts and must never enter the repository.

Every future binary must visibly identify and provide equal access to exact Corresponding Source. The public source page is <https://npo-nt.ru/open-source/mika-deid/>. External patient-facing binary distribution remains blocked by the non-source release gates in `RELEASE_GATES.md` and by the requirement to pair each binary with its exact commit and source archive.

## Future hardening

- Move untrusted file parsing into an OS sandbox or restricted helper process.
- Encrypt transient page cache and destroy the ephemeral key on exit.
- Add a local face/signature detector while retaining human review.
- Add a reproducible signed installer pipeline.
- Add signed, pinned, offline OCR/model bundles.
- Add a consented direct-upload module separated from the de-identification engine.
- Add DICOM only as a separate standards-based component.
