1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177---
title: Architecture
date: 2026-03-23
author: Equalify Tech Team
description: System architecture, components, data flow, and deployment topology of Equalify Reflow.
---
# Architecture
Equalify Reflow is composed of three services that work together: a conversion engine, a WordPress plugin, and a feedback service. This page covers the conversion engine architecture in detail.
## System Components
```
┌─────────────────┐
│ WordPress Site │
│ (reflow-wp) │
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────┐
│ Equalify Reflow API │
│ (FastAPI + Uvicorn) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│ │ Document │ │ Pipeline │ │ Approval ││
│ │ Endpoints │ │ Viewer │ │ Endpoints ││
│ └─────┬────┘ └─────┬────┘ └────────┬─────────┘│
│ │ │ │ │
│ ┌─────┴─────────────┴────────────────┴─────────┐│
│ │ Service Layer ││
│ │ ┌────────────┐ ┌──────────┐ ┌───────────┐ ││
│ │ │ Processing │ │ Storage │ │ Queue │ ││
│ │ │ Service │ │ Service │ │ Service │ ││
│ │ └──────┬─────┘ └─────┬───┘ └─────┬─────┘ ││
│ └─────────┼──────────────┼─────────────┼───────┘│
└────────────┼──────────────┼─────────────┼────────┘
│ │ │
┌────────┼──────────────┼─────────────┼────────┐
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Docling │ │ S3 │ │ Redis │ │
│ │ Serve │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ Infrastructure │
└──────────────────────────────────────────────┘
```
*System component diagram showing the three-layer architecture: a WordPress site connects to the Equalify Reflow API (FastAPI + Uvicorn), which contains Document, Pipeline Viewer, and Approval endpoint groups. These feed into a shared Service Layer (Processing, Storage, and Queue services), which communicates with the infrastructure layer containing Docling Serve (PDF extraction), S3 (document storage), and Redis (job state and queuing).*
### Conversion Engine (equalify-reflow)
The core service. A FastAPI application that accepts PDF uploads, runs the five-stage pipeline, and returns accessible markdown.
**Key responsibilities:**
- REST API for document submission, status tracking, and SSE streaming
- PII scanning via Microsoft Presidio before any AI processing
- Five-stage conversion pipeline with AI agents (Claude via AWS Bedrock)
- Change ledger recording every edit with reasoning
- Job state management and event streaming via Redis
- Document storage and retrieval via S3
### WordPress Plugin (equalify-reflow-wp)
Integrates the conversion engine with WordPress. Administrators process PDFs from the Media Library; results are stored as WordPress posts and served through a built-in viewer.
See [use the WordPress plugin](../how-to/use-the-wordpress-plugin.md).
### Feedback Service (equalify-reflow-feedback)
A separate FastAPI + SQLite service that collects issue reports and text corrections from viewers. Provides filtering, aggregation, and a Metabase dashboard for analyzing feedback patterns.
## Data Flow
### Standard Processing Flow
```
1. PDF uploaded → S3 temp bucket
2. PII scan (Microsoft Presidio)
├─ Pass → queue for processing
└─ Fail → hold for human approval
3. Pipeline processing (5 stages)
└─ Each stage: AI agent processes → edits recorded in change ledger
4. Results stored in S3 results bucket
5. Job marked completed → SSE event emitted
6. Client downloads markdown + figures via pre-signed S3 URLs
```
*Data flow diagram showing the six steps of document processing: PDF upload to S3, PII scanning with pass/fail branching, five-stage pipeline processing with change ledger recording, results storage in S3, job completion notification via SSE, and client download of markdown and figures via pre-signed URLs.*
### SSE Streaming Architecture
Real-time progress is delivered via Server-Sent Events. The architecture is designed so the pipeline runs independently of client connections:
1. Client submits a document and receives a `job_id`
2. Client requests a single-use **stream token** (because `EventSource` can't send headers)
3. Client opens SSE connection with the token as a query parameter
4. Pipeline emits events to Redis pub/sub → SSE endpoint relays to connected clients
5. If the client disconnects, the pipeline continues. The client can reconnect and replay missed events
This pattern is used by both the built-in viewer and the WordPress plugin.
## Service Layer
### ProcessingService
Orchestrates the conversion pipeline. Manages the dossier (document context that accumulates through pipeline stages), coordinates AI agents, and records the change ledger.
### StorageService
Wraps S3 operations with circuit breakers and retry logic. Handles upload, download, and pre-signed URL generation for both temp and results buckets.
### QueueService
Redis-based job queuing. Documents are enqueued after PII scanning and dequeued by background workers.
### JobService
Manages job state in Redis using Lua scripts for atomic operations. Tracks status transitions, stores metadata, and publishes state-change events.
### PIIDetectionService
Scans document text using Microsoft Presidio. Detects email addresses, phone numbers, SSNs, and other PII entity types. Configurable confidence threshold.
## AI Agent Architecture
The pipeline uses [PydanticAI](https://ai.pydantic.dev/) to define agents with tool-call interfaces. Each agent:
- Receives the page as both an **image** and **markdown text**
- Has access to the **dossier** — accumulated document context from prior stages
- Makes edits through **tool calls**, each requiring a reasoning explanation
- Can spawn **sub-agents** for specialized tasks (alt text, tables, lists)
Tool registration is **conditional** — vision tools are only provided when the task involves images, reducing prompt token waste for text-only work.
### Model
The pipeline runs on Claude 4.5 models in two tiers — **Haiku 4.5** (the default, used by every current agent call) and **Sonnet 4.5** (reserved for heavier analysis). The AI backend is pluggable: production runs against AWS Bedrock; local development and alternative deployments can point at Anthropic direct via `ANTHROPIC_API_KEY`. The factory in the contributor repo selects backend + tier at call time without any hardcoded model IDs.
## Infrastructure
### Local Development
```bash
make dev # Starts everything via Docker Compose
```
| Service | Port | Purpose |
|---------|------|---------|
| API Gateway | 8080 | FastAPI application |
| Redis | 6379 | Job state, queues, pub/sub |
| Floci | 4566 | S3 emulation (lightweight alternative to LocalStack) |
| Docling Serve | 5001 | PDF extraction sidecar |
| Prometheus | 9090 | Metrics collection |
| Grafana | 3001 | Monitoring dashboards |
| Jaeger | 16686 | Distributed tracing |
Code is mounted into the container with hot reload enabled — edit files on your host and changes take effect immediately.
### Production (AWS ECS)
- **ECS Fargate** — containerized API with auto-scaling
- **S3** — temp and results buckets with lifecycle policies
- **Redis (ElastiCache)** — managed Redis for job state
- **AWS Bedrock** — Claude model access (no API keys needed, uses IAM roles)
- **CloudWatch** — logs and metrics forwarding
- **Terraform** — infrastructure as code in `terraform/`
### Resilience
- **Circuit breakers** on S3 operations — prevent cascading failures when S3 is degraded
- **Retry logic** with exponential backoff on transient failures
- **Health checks** — `/health` verifies Redis, S3, and queue connectivity; `/health/ready` for orchestration probes
- **Graceful degradation** — pipeline steps that fail non-fatally emit an error event and continue