Plugin system

Plug-and-play architecture: add or remove parsers without changing the orchestrator, API, or HTML UI.

Flow

flowchart LR
  UI[HTML UI] --> API[FastAPI]
  API --> Orch[orchestrator]
  Orch --> Reg[registry]
  Reg --> P1[tesseract]
  Reg --> P2[docai]
  Reg --> E1[gemini-extract]

Protocols

All OCR parsers implement OcrParser:

• info() -> ParserInfo — includes enabled and disabled_reason
• parse(document) -> list[OcrPageResult]

All extractors implement Extractor:

• info() -> ParserInfo
• extract(ocr_text, document) -> list[AnalyteRow]

Built-in plugins

ID	Kind	Enabled when
tesseract	OCR	tesseract on PATH (included in Docker image)
docai	OCR	GCP_PROJECT_ID + DOCAI_LAYOUT_PROCESSOR_ID
gemini-extract	Extract	GCP_PROJECT_ID + credentials

Add a new parser

1. Create faxautomation/plugins/ocr/my_engine.py (or extract/)
2. Implement the protocol
3. Register in faxautomation/plugins/__init__.py:

from faxautomation.plugins.ocr import my_engine
register_ocr_parser(my_engine.parser)

1. Add tests in tests/
2. Update this page

No changes required to orchestrator.py, API routes, or app.js.

Remove a parser

Delete the module and remove the register_* line from plugins/__init__.py.

Registry API

• register_ocr_parser(parser)
• register_extractor(extractor)
• list_ocr_parsers() / list_extractors()
• get_ocr_parser(id) / get_extractor(id)