# bakrianoo/temporal-101-course architecture

> Architecture diagram of the GitHub repository bakrianoo/temporal-101-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bakrianoo/temporal-101-course
- Repository: https://github.com/bakrianoo/temporal-101-course

## Overview

This is a Temporal 101 teaching repository, not one production application: it progresses from a synchronous S3-to-Markdown script to a Temporal-orchestrated version, then to multi-document AI contract review with human approval and revision. The FastAPI client starts workflows and exposes status, report, and review controls; workers register workflow and activity code with Temporal. The README documents the product capabilities, while sampled source supports the specific calls shown below. The local Temporal server is an external runtime dependency; infrastructure and setup files are not mapped as product components.

Main entry points: [`apps/ai-contract-review/activities.py`](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/activities.py) (Review activities), [`apps/pdf-extraction-02-temporal/activities.py`](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/activities.py) (PDF activities), [`apps/ai-contract-review/worker.py`](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/worker.py) (Review worker), [`apps/ai-contract-review/parent_workflow.py`](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/parent_workflow.py) (Review coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_client_api["FastAPI client<br/>[main.py]"]
end

subgraph group_plain["Plain PDF"]
  node_plain_pipeline["Synchronous pipeline<br/>[process_pdf.py]"]
end

subgraph group_temporal_pdf["Temporal PDF"]
  node_pdf_worker["PDF worker<br/>[worker.py]"]
  node_pdf_workflow["PDF workflow"]
  node_pdf_activities["PDF activities<br/>[activities.py]"]
  node_pdf_helpers["S3 helpers and data<br/>[helpers.py]"]
end

subgraph group_review["Contract Review"]
  node_review_worker["Review worker<br/>[worker.py]"]
  node_parent_workflow["Review coordinator<br/>[parent_workflow.py]"]
  node_child_workflow["Document analysis<br/>[child_workflow.py]"]
  node_review_activities["Review activities<br/>[activities.py]"]
  node_review_prompts["Analysis prompts<br/>[prompts.py]"]
end

node_user(("API caller"))
node_temporal["Temporal server"]
node_s3[("S3 storage")]
node_pdf_library["PDF-to-Markdown"]
node_openrouter["OpenRouter LLM"]
node_reviewer(("Human reviewer"))

node_user -->|"calls routes"| node_client_api
node_user -->|"runs script"| node_plain_pipeline
node_plain_pipeline -->|"downloads and uploads"| node_s3
node_plain_pipeline -->|"converts PDF"| node_pdf_library
node_client_api -->|"starts and queries workflows"| node_temporal
node_temporal -->|"dispatches tasks"| node_pdf_worker
node_pdf_worker -->|"registers workflow"| node_pdf_workflow
node_pdf_worker -->|"registers activities"| node_pdf_activities
node_pdf_workflow -->|"executes activities"| node_pdf_activities
node_pdf_activities -->|"uses S3 helpers"| node_pdf_helpers
node_pdf_activities -->|"downloads and uploads"| node_s3
node_pdf_activities -->|"converts PDF"| node_pdf_library
node_temporal -->|"dispatches tasks"| node_review_worker
node_review_worker -->|"registers workflow"| node_parent_workflow
node_review_worker -->|"registers workflow"| node_child_workflow
node_review_worker -->|"registers activities"| node_review_activities
node_parent_workflow -->|"starts child workflows"| node_child_workflow
node_parent_workflow -->|"executes synthesis and revision"| node_review_activities
node_child_workflow -->|"executes extraction and analysis"| node_review_activities
node_child_workflow -->|"formats analysis prompt"| node_review_prompts
node_parent_workflow -->|"formats report prompts"| node_review_prompts
node_review_activities -->|"downloads PDFs"| node_s3
node_review_activities -->|"extracts PDF text"| node_pdf_library
node_review_activities -->|"sends LLM prompts"| node_openrouter
node_reviewer -->|"assigns and decides"| node_client_api
node_client_api -->|"queries and signals review"| node_temporal

click node_client_api "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/client-app/main.py"
click node_plain_pipeline "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-01-plain/process_pdf.py"
click node_pdf_worker "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/worker.py"
click node_pdf_workflow "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/workflow_process_pdf.py"
click node_pdf_activities "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/activities.py"
click node_pdf_helpers "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/helpers.py"
click node_review_worker "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/worker.py"
click node_parent_workflow "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/parent_workflow.py"
click node_child_workflow "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/child_workflow.py"
click node_review_activities "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/activities.py"
click node_review_prompts "https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/prompts.py"

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_client_api,node_reviewer toneBlue
class node_plain_pipeline,node_s3 toneAmber
class node_pdf_worker,node_pdf_workflow,node_pdf_activities,node_pdf_helpers,node_user,node_temporal,node_openrouter toneMint
class node_review_worker,node_parent_workflow,node_child_workflow,node_review_activities,node_review_prompts toneRose
class node_pdf_library toneIndigo
```

## Components

### Client API

- [FastAPI client](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/client-app/main.py): `apps/client-app/main.py`

### Plain PDF

- [Synchronous pipeline](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-01-plain/process_pdf.py): `apps/pdf-extraction-01-plain/process_pdf.py`

### Temporal PDF

- [PDF worker](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/worker.py): `apps/pdf-extraction-02-temporal/worker.py`
- [PDF workflow](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/workflow_process_pdf.py): `apps/pdf-extraction-02-temporal/workflow_process_pdf.py`
- [PDF activities](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/activities.py): `apps/pdf-extraction-02-temporal/activities.py`
- [S3 helpers and data](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/pdf-extraction-02-temporal/helpers.py): `apps/pdf-extraction-02-temporal/helpers.py`

### Contract Review

- [Review worker](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/worker.py): `apps/ai-contract-review/worker.py`
- [Review coordinator](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/parent_workflow.py): `apps/ai-contract-review/parent_workflow.py`
- [Document analysis](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/child_workflow.py): `apps/ai-contract-review/child_workflow.py`
- [Review activities](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/activities.py): `apps/ai-contract-review/activities.py`
- [Analysis prompts](https://github.com/bakrianoo/temporal-101-course/blob/main/apps/ai-contract-review/prompts.py): `apps/ai-contract-review/prompts.py`

### Other components

- **API caller**
- **Temporal server**
- **S3 storage**
- **PDF-to-Markdown**
- **OpenRouter LLM**
- **Human reviewer**

## Connections

- API caller → FastAPI client: calls routes
- API caller → Synchronous pipeline: runs script
- Synchronous pipeline → S3 storage: downloads and uploads
- Synchronous pipeline → PDF-to-Markdown: converts PDF
- FastAPI client → Temporal server: starts and queries workflows
- Temporal server → PDF worker: dispatches tasks
- PDF worker → PDF workflow: registers workflow
- PDF worker → PDF activities: registers activities
- PDF workflow → PDF activities: executes activities
- PDF activities → S3 helpers and data: uses S3 helpers
- PDF activities → S3 storage: downloads and uploads
- PDF activities → PDF-to-Markdown: converts PDF
- Temporal server → Review worker: dispatches tasks
- Review worker → Review coordinator: registers workflow
- Review worker → Document analysis: registers workflow
- Review worker → Review activities: registers activities
- Review coordinator → Document analysis: starts child workflows
- Review coordinator → Review activities: executes synthesis and revision
- Document analysis → Review activities: executes extraction and analysis
- Document analysis → Analysis prompts: formats analysis prompt
- Review coordinator → Analysis prompts: formats report prompts
- Review activities → S3 storage: downloads PDFs
- Review activities → PDF-to-Markdown: extracts PDF text
- Review activities → OpenRouter LLM: sends LLM prompts
- Human reviewer → FastAPI client: assigns and decides
- FastAPI client → Temporal server: queries and signals review