# zipstack/unstract architecture

> Architecture diagram of the GitHub repository zipstack/unstract, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zipstack/unstract
- Repository: https://github.com/zipstack/unstract

## Overview

Unstract turns unstructured documents into structured JSON using natural-language extraction prompts. The user-facing workflow starts in the web app, where teams configure Prompt Studio profiles and deploy extraction through an API or ETL pipeline; workers process files and return results. The README also documents MCP and n8n integrations, and the tree shows corresponding backend components. Several backend and worker links below are documented capabilities rather than inspected call paths, so those edges cite the README; sampled implementation details are limited.

Main entry points: [`backend/pipeline_v2`](https://github.com/zipstack/unstract/tree/main/backend/pipeline_v2) (ETL pipeline), [`workers`](https://github.com/zipstack/unstract/tree/main/workers) (Processing workers), [`frontend/src/routes/useMainAppRoutes.jsx`](https://github.com/zipstack/unstract/blob/main/frontend/src/routes/useMainAppRoutes.jsx) (Web application), [`backend/prompt_studio`](https://github.com/zipstack/unstract/tree/main/backend/prompt_studio) (Prompt Studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web application"]
  node_pipeline_ui["Pipeline console<br/>[Pipelines.jsx]"]
end

subgraph group_extraction["Extraction and processing"]
  node_prompt_studio["Prompt Studio"]
  node_prompt_outputs["Output management"]
  node_connectors["File connectors"]
  node_filtering["File filtering<br/>[filter_pipeline.py]"]
  node_workers["Processing workers"]
  node_llm["LLM providers"]
  node_structured_result["Structured JSON"]
end

subgraph group_delivery["Deployment and integration"]
  node_api_deployment["API deployment"]
  node_etl_pipeline["ETL pipeline"]
  node_mcp["MCP server"]
  node_n8n["n8n integration"]
end

subgraph group_platform["Platform services"]
  node_account["Accounts and auth"]
  node_account_store[("Account records<br/>[models.py]")]
  node_pipeline_store[("Pipeline records<br/>[models.py]")]
  node_platform_services["Platform services"]
end

node_user(("Team user"))

node_user -->|"configures"| node_web
node_web -->|"defines prompts"| node_prompt_studio
node_web -->|"manages deployments"| node_pipeline_ui
node_pipeline_ui -.->|"manages pipelines"| node_etl_pipeline
node_prompt_studio -->|"formats outputs"| node_prompt_outputs
node_connectors -.->|"supplies files"| node_workers
node_workers -->|"filters batches"| node_filtering
node_workers -.->|"runs extraction"| node_prompt_studio
node_prompt_studio -.->|"queries models"| node_llm
node_prompt_outputs -->|"produces JSON"| node_structured_result
node_user -->|"submits documents"| node_api_deployment
node_api_deployment -.->|"dispatches processing"| node_workers
node_workers -->|"returns results"| node_structured_result
node_user -->|"configures ETL"| node_etl_pipeline
node_etl_pipeline -->|"pulls documents"| node_connectors
node_etl_pipeline -.->|"processes files"| node_workers
node_etl_pipeline -->|"loads results"| node_connectors
node_user -->|"connects agent"| node_mcp
node_user -->|"uses automation"| node_n8n
node_account -->|"persists accounts"| node_account_store
node_etl_pipeline -.->|"tracks pipeline"| node_pipeline_store
node_web -.->|"authenticates"| node_account
node_api_deployment -.->|"uses services"| node_platform_services

click node_web "https://github.com/zipstack/unstract/blob/main/frontend/src/routes/useMainAppRoutes.jsx"
click node_pipeline_ui "https://github.com/zipstack/unstract/blob/main/frontend/src/components/pipelines-or-deployments/pipelines/Pipelines.jsx"
click node_prompt_studio "https://github.com/zipstack/unstract/tree/main/backend/prompt_studio"
click node_prompt_outputs "https://github.com/zipstack/unstract/blob/main/backend/prompt_studio/prompt_studio_output_manager_v2/output_manager_helper.py"
click node_connectors "https://github.com/zipstack/unstract/tree/main/unstract/connectors/src/unstract/connectors/filesystems"
click node_filtering "https://github.com/zipstack/unstract/blob/main/workers/shared/processing/filter_pipeline.py"
click node_workers "https://github.com/zipstack/unstract/tree/main/workers"
click node_llm "https://github.com/zipstack/unstract/tree/main/unstract/connectors"
click node_api_deployment "https://github.com/zipstack/unstract/tree/main/backend/api_v2"
click node_etl_pipeline "https://github.com/zipstack/unstract/tree/main/backend/pipeline_v2"
click node_mcp "https://github.com/zipstack/unstract/tree/main/backend/mcp_server"
click node_account "https://github.com/zipstack/unstract/tree/main/backend/account_v2"
click node_account_store "https://github.com/zipstack/unstract/blob/main/backend/account_v2/models.py"
click node_pipeline_store "https://github.com/zipstack/unstract/blob/main/backend/pipeline_v2/models.py"
click node_platform_services "https://github.com/zipstack/unstract/tree/main/backend/backend"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_pipeline_ui,node_user toneBlue
class node_prompt_studio,node_prompt_outputs,node_connectors,node_filtering,node_workers,node_llm,node_structured_result toneAmber
class node_api_deployment,node_etl_pipeline,node_mcp,node_n8n toneMint
class node_account,node_account_store,node_pipeline_store,node_platform_services toneRose
```

## Components

### User experience

- [Web application](https://github.com/zipstack/unstract/blob/main/frontend/src/routes/useMainAppRoutes.jsx): `frontend/src/routes/useMainAppRoutes.jsx`
- [Pipeline console](https://github.com/zipstack/unstract/blob/main/frontend/src/components/pipelines-or-deployments/pipelines/Pipelines.jsx): `frontend/src/components/pipelines-or-deployments/pipelines/Pipelines.jsx`

### Extraction and processing

- [Prompt Studio](https://github.com/zipstack/unstract/tree/main/backend/prompt_studio): `backend/prompt_studio`
- [Output management](https://github.com/zipstack/unstract/blob/main/backend/prompt_studio/prompt_studio_output_manager_v2/output_manager_helper.py): `backend/prompt_studio/prompt_studio_output_manager_v2/output_manager_helper.py`
- [File connectors](https://github.com/zipstack/unstract/tree/main/unstract/connectors/src/unstract/connectors/filesystems): `unstract/connectors/src/unstract/connectors/filesystems`
- [File filtering](https://github.com/zipstack/unstract/blob/main/workers/shared/processing/filter_pipeline.py): `workers/shared/processing/filter_pipeline.py`
- [Processing workers](https://github.com/zipstack/unstract/tree/main/workers): `workers`
- [LLM providers](https://github.com/zipstack/unstract/tree/main/unstract/connectors): `unstract/connectors`
- **Structured JSON**

### Deployment and integration

- [API deployment](https://github.com/zipstack/unstract/tree/main/backend/api_v2): `backend/api_v2`
- [ETL pipeline](https://github.com/zipstack/unstract/tree/main/backend/pipeline_v2): `backend/pipeline_v2`
- [MCP server](https://github.com/zipstack/unstract/tree/main/backend/mcp_server): `backend/mcp_server`
- **n8n integration**

### Platform services

- [Accounts and auth](https://github.com/zipstack/unstract/tree/main/backend/account_v2): `backend/account_v2`
- [Account records](https://github.com/zipstack/unstract/blob/main/backend/account_v2/models.py): `backend/account_v2/models.py`
- [Pipeline records](https://github.com/zipstack/unstract/blob/main/backend/pipeline_v2/models.py): `backend/pipeline_v2/models.py`
- [Platform services](https://github.com/zipstack/unstract/tree/main/backend/backend): `backend/backend`

### Other components

- **Team user**

## Connections

- Team user → Web application: configures (evidence: `README.md`)
- Web application → Prompt Studio: defines prompts (evidence: `README.md`)
- Web application → Pipeline console: manages deployments (evidence: `frontend/src/routes/useMainAppRoutes.jsx`)
- Pipeline console → ETL pipeline: manages pipelines
- Prompt Studio → Output management: formats outputs (evidence: `backend/prompt_studio/prompt_studio_output_manager_v2/output_manager_helper.py`)
- File connectors → Processing workers: supplies files (evidence: `unstract/connectors/src/unstract/connectors/filesystems/google_cloud_storage/google_cloud_storage.py`)
- Processing workers → File filtering: filters batches (evidence: `workers/shared/processing/filter_pipeline.py`)
- Processing workers → Prompt Studio: runs extraction (evidence: `backend/prompt_studio/prompt_studio_output_manager_v2/output_manager_helper.py`)
- Prompt Studio → LLM providers: queries models
- Output management → Structured JSON: produces JSON (evidence: `README.md`)
- Team user → API deployment: submits documents (evidence: `README.md`)
- API deployment → Processing workers: dispatches processing
- Processing workers → Structured JSON: returns results (evidence: `README.md`)
- Team user → ETL pipeline: configures ETL (evidence: `README.md`)
- ETL pipeline → File connectors: pulls documents (evidence: `README.md`)
- ETL pipeline → Processing workers: processes files (evidence: `backend/pipeline_v2/pipeline_processor.py`)
- ETL pipeline → File connectors: loads results (evidence: `README.md`)
- Team user → MCP server: connects agent (evidence: `README.md`)
- Team user → n8n integration: uses automation (evidence: `README.md`)
- Accounts and auth → Account records: persists accounts (evidence: `backend/account_v2/models.py`)
- ETL pipeline → Pipeline records: tracks pipeline (evidence: `backend/pipeline_v2/pipeline_processor.py`)
- Web application → Accounts and auth: authenticates
- API deployment → Platform services: uses services
