# 221fa19027-ui/crazypdf architecture

> Architecture diagram of the GitHub repository 221fa19027-ui/crazypdf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/221fa19027-ui/crazypdf
- Repository: https://github.com/221fa19027-ui/crazypdf

## Overview

CrazyPDF is a web-based PDF productivity workspace. Users select a tool, submit documents and options, and receive a processed result for download; the catalog spans organization, optimization, conversion, editing, security, and AI. The frontend’s tool page and API client form the visible request path, while FastAPI exposes processing and account endpoints. Backend processing modules implement the domain capabilities, with temporary-file cleanup and database-backed job metadata supporting ephemeral processing. Processor dispatch details are not sampled, so those links are documented at the product level rather than inferred from imports.

Main entry points: [`backend/app/api/v1/endpoints/tools.py`](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/tools.py) (Tool processing API), [`backend/app/api/v1/api.py`](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/api.py) (API router), [`backend/app/services/auth_service.py`](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/auth_service.py) (Google auth), [`frontend/src/pages/ToolDetailPage.tsx`](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/pages/ToolDetailPage.tsx) (Tool workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspace"]
  node_tool_ui["Tool workspace<br/>[ToolDetailPage.tsx]"]
  node_tool_catalog["Tool catalog<br/>[tools.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_auth_context["Login state<br/>[AuthContext.tsx]"]
  node_routing["App routes<br/>[AppRoutes.tsx]"]
end

subgraph group_api["API and accounts"]
  node_tools_api["Tool processing API<br/>[tools.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_user_api["User dashboard API<br/>[user.py]"]
  node_job_api["Job API<br/>[jobs.py]"]
  node_api_router["API router<br/>[api.py]"]
  node_auth_service["Google auth<br/>[auth_service.py]"]
end

subgraph group_processing["PDF processing"]
  node_organize["Organize PDFs<br/>[organize.py]"]
  node_optimize["Optimize PDFs<br/>[optimize.py]"]
  node_convert_from["PDF conversions<br/>[convert_from.py]"]
  node_convert_to["Create PDFs<br/>[convert_to.py]"]
  node_edit["Edit PDFs<br/>[edit.py]"]
  node_security_pdf["PDF security<br/>[security_pdf.py]"]
  node_ai_tools["AI document tools<br/>[ai_tools.py]"]
end

subgraph group_privacy["Privacy and state"]
  node_ssrf["SSRF guard<br/>[ssrf_guard.py]"]
  node_cleanup["Expiry cleanup<br/>[cleanup_service.py]"]
  node_storage["Temporary storage<br/>[storage_service.py]"]
  node_database[("Application database<br/>[database.py]")]
  node_user_model["User records<br/>[user.py]"]
  node_job_model["Processing jobs<br/>[job.py]"]
end

node_user(("PDF user"))
node_google(("Google identity"))
node_download["Downloaded result"]

node_user -->|"selects tool"| node_tool_ui
node_routing -->|"routes to"| node_tool_ui
node_tool_ui -->|"uses definitions"| node_tool_catalog
node_tool_ui -->|"submits files"| node_api_client
node_api_client -->|"POSTs tool request"| node_tools_api
node_api_router -->|"registers route"| node_tools_api
node_api_router -->|"registers route"| node_auth_api
node_api_router -->|"registers route"| node_user_api
node_api_router -->|"registers route"| node_job_api
node_user -->|"signs in"| node_auth_context
node_auth_context -->|"requests login"| node_api_client
node_api_client -->|"POSTs credentials"| node_auth_api
node_auth_api -->|"verifies identity"| node_auth_service
node_auth_service -->|"verifies token"| node_google
node_auth_service -->|"reads and updates"| node_user_model
node_auth_service -->|"uses session"| node_database
node_tools_api -->|"dispatches processing"| node_organize
node_tools_api -->|"dispatches processing"| node_optimize
node_tools_api -->|"dispatches processing"| node_convert_from
node_tools_api -->|"dispatches processing"| node_convert_to
node_tools_api -->|"dispatches processing"| node_edit
node_tools_api -->|"dispatches processing"| node_security_pdf
node_tools_api -->|"dispatches processing"| node_ai_tools
node_tools_api -.->|"guards HTML fetch"| node_ssrf
node_tools_api -.->|"stages temporary files"| node_storage
node_tools_api -.->|"records job"| node_job_model
node_tools_api -.->|"returns download link"| node_download
node_cleanup -->|"checks expiry"| node_job_model
node_cleanup -->|"purges artifacts"| node_storage
node_cleanup -->|"queries jobs"| node_database

click node_tool_ui "https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/pages/ToolDetailPage.tsx"
click node_tool_catalog "https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/types/tools.ts"
click node_api_client "https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/services/api.ts"
click node_auth_context "https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/context/AuthContext.tsx"
click node_routing "https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_tools_api "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/tools.py"
click node_auth_api "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_user_api "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/user.py"
click node_job_api "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/jobs.py"
click node_api_router "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/api.py"
click node_auth_service "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/auth_service.py"
click node_organize "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/organize.py"
click node_optimize "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/optimize.py"
click node_convert_from "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/convert_from.py"
click node_convert_to "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/convert_to.py"
click node_edit "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/edit.py"
click node_security_pdf "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/security_pdf.py"
click node_ai_tools "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/ai_tools.py"
click node_ssrf "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/security/ssrf_guard.py"
click node_cleanup "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/cleanup_service.py"
click node_storage "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/storage_service.py"
click node_database "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/core/database.py"
click node_user_model "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/models/user.py"
click node_job_model "https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/models/job.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_tool_ui,node_tool_catalog,node_api_client,node_auth_context,node_routing,node_user toneBlue
class node_tools_api,node_auth_api,node_user_api,node_job_api,node_api_router,node_auth_service toneAmber
class node_organize,node_optimize,node_convert_from,node_convert_to,node_edit,node_security_pdf,node_ai_tools toneMint
class node_ssrf,node_cleanup,node_storage,node_database,node_user_model,node_job_model toneRose
class node_google,node_download toneIndigo
```

## Components

### Web workspace

- [Tool workspace](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/pages/ToolDetailPage.tsx): `frontend/src/pages/ToolDetailPage.tsx`
- [Tool catalog](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/types/tools.ts): `frontend/src/types/tools.ts`
- [API client](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Login state](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [App routes](https://github.com/221fa19027-ui/crazypdf/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`

### API and accounts

- [Tool processing API](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/tools.py): `backend/app/api/v1/endpoints/tools.py`
- [Authentication API](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [User dashboard API](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/user.py): `backend/app/api/v1/endpoints/user.py`
- [Job API](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/endpoints/jobs.py): `backend/app/api/v1/endpoints/jobs.py`
- [API router](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/api/v1/api.py): `backend/app/api/v1/api.py`
- [Google auth](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### PDF processing

- [Organize PDFs](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/organize.py): `backend/app/processors/organize.py`
- [Optimize PDFs](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/optimize.py): `backend/app/processors/optimize.py`
- [PDF conversions](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/convert_from.py): `backend/app/processors/convert_from.py`
- [Create PDFs](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/convert_to.py): `backend/app/processors/convert_to.py`
- [Edit PDFs](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/edit.py): `backend/app/processors/edit.py`
- [PDF security](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/security_pdf.py): `backend/app/processors/security_pdf.py`
- [AI document tools](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/processors/ai_tools.py): `backend/app/processors/ai_tools.py`

### Privacy and state

- [SSRF guard](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/security/ssrf_guard.py): `backend/app/security/ssrf_guard.py`
- [Expiry cleanup](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/cleanup_service.py): `backend/app/services/cleanup_service.py`
- [Temporary storage](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [Application database](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [User records](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Processing jobs](https://github.com/221fa19027-ui/crazypdf/blob/main/backend/app/models/job.py): `backend/app/models/job.py`

### Other components

- **PDF user**
- **Google identity**
- **Downloaded result**

## Connections

- PDF user → Tool workspace: selects tool
- App routes → Tool workspace: routes to (evidence: `frontend/src/routes/AppRoutes.tsx`)
- Tool workspace → Tool catalog: uses definitions (evidence: `frontend/src/pages/ToolDetailPage.tsx`)
- Tool workspace → API client: submits files (evidence: `frontend/src/pages/ToolDetailPage.tsx`)
- API client → Tool processing API: POSTs tool request (evidence: `frontend/src/services/api.ts`)
- API router → Tool processing API: registers route (evidence: `backend/app/api/v1/api.py`)
- API router → Authentication API: registers route (evidence: `backend/app/api/v1/api.py`)
- API router → User dashboard API: registers route (evidence: `backend/app/api/v1/api.py`)
- API router → Job API: registers route (evidence: `backend/app/api/v1/api.py`)
- PDF user → Login state: signs in (evidence: `frontend/src/context/AuthContext.tsx`)
- Login state → API client: requests login (evidence: `frontend/src/context/AuthContext.tsx`)
- API client → Authentication API: POSTs credentials (evidence: `frontend/src/services/api.ts`)
- Authentication API → Google auth: verifies identity (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Google auth → Google identity: verifies token (evidence: `backend/app/services/auth_service.py`)
- Google auth → User records: reads and updates (evidence: `backend/app/services/auth_service.py`)
- Google auth → Application database: uses session (evidence: `backend/app/services/auth_service.py`)
- Tool processing API → Organize PDFs: dispatches processing (evidence: `README.md`)
- Tool processing API → Optimize PDFs: dispatches processing (evidence: `README.md`)
- Tool processing API → PDF conversions: dispatches processing (evidence: `README.md`)
- Tool processing API → Create PDFs: dispatches processing (evidence: `README.md`)
- Tool processing API → Edit PDFs: dispatches processing (evidence: `README.md`)
- Tool processing API → PDF security: dispatches processing (evidence: `README.md`)
- Tool processing API → AI document tools: dispatches processing (evidence: `README.md`)
- Tool processing API → SSRF guard: guards HTML fetch
- Tool processing API → Temporary storage: stages temporary files
- Tool processing API → Processing jobs: records job
- Tool processing API → Downloaded result: returns download link
- Expiry cleanup → Processing jobs: checks expiry (evidence: `backend/app/services/cleanup_service.py`)
- Expiry cleanup → Temporary storage: purges artifacts (evidence: `backend/app/services/cleanup_service.py`)
- Expiry cleanup → Application database: queries jobs (evidence: `backend/app/services/cleanup_service.py`)
