# amalitech-training-academy/doclift architecture

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

- Interactive diagram: https://gitdiagram.com/amalitech-training-academy/doclift
- Repository: https://github.com/amalitech-training-academy/doclift

## Overview

Doclift is a PDF upload and conversion experience: users select a document, follow a session’s progress, and view conversion results. The backend exposes an upload endpoint whose service is documented to validate and store the PDF and create a job; the sampled extraction implementation extracts page text spans and images and detects candidate table regions. The web context persists draft files and session state locally. The README is empty, and sampled source does not establish how web screens connect to the backend or how extraction feeds a completed result, so those links are omitted.

Main entry points: [`apps/web/src/context/ConversionContext.tsx`](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/context/ConversionContext.tsx) (Conversion context), [`apps/backend/src/main/java/com/amalitech/backend/controller/UploadController.java`](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/controller/UploadController.java) (Upload endpoint), [`apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionService.java`](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionService.java) (PDF extraction), [`apps/web/src/components/upload/UploadScreen.tsx`](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/upload/UploadScreen.tsx) (Upload screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_upload_ui["Upload screen<br/>[UploadScreen.tsx]"]
  node_progress_ui["Progress screen<br/>[ProgressScreen.tsx]"]
  node_results_ui["Results screen<br/>[ResultsScreen.tsx]"]
  node_conversion_context["Conversion context"]
  node_draft_store[("Draft file store<br/>[fileStorage.ts]")]
  node_session_store[("Session persistence")]
end

subgraph group_ingest["Backend upload"]
  node_upload_controller["Upload endpoint"]
  node_upload_service["Upload service<br/>[UploadService.java]"]
  node_validation_service["PDF validation"]
  node_file_storage["File storage"]
end

subgraph group_analysis["PDF analysis"]
  node_pdf_extraction["PDF extraction"]
  node_extraction_result["Page extraction data"]
end

subgraph group_jobs["Job state"]
  node_job_service["Job service<br/>[JobService.java]"]
  node_job_repository[("Job repository<br/>[JobRepository.java]")]
  node_job_file_repository[("Job file repository")]
end

node_user(("Document user"))

node_user -->|"selects PDF"| node_upload_ui
node_conversion_context -->|"saves and restores"| node_draft_store
node_conversion_context -->|"persists session"| node_session_store
node_upload_controller -->|"handles upload"| node_upload_service
node_pdf_extraction -->|"produces"| node_extraction_result

click node_upload_ui "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/upload/UploadScreen.tsx"
click node_progress_ui "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/progress/ProgressScreen.tsx"
click node_results_ui "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/results/ResultsScreen.tsx"
click node_conversion_context "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/context/ConversionContext.tsx"
click node_draft_store "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/lib/fileStorage.ts"
click node_session_store "https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/lib/conversionSession.ts"
click node_upload_controller "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/controller/UploadController.java"
click node_upload_service "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/UploadService.java"
click node_validation_service "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfValidationService.java"
click node_file_storage "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/FileStorageService.java"
click node_pdf_extraction "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionService.java"
click node_extraction_result "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionResult.java"
click node_job_service "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/JobService.java"
click node_job_repository "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/repository/JobRepository.java"
click node_job_file_repository "https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/repository/JobFileRepository.java"

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_upload_ui,node_progress_ui,node_results_ui,node_conversion_context,node_draft_store,node_session_store,node_user toneBlue
class node_upload_controller,node_upload_service,node_validation_service,node_file_storage toneAmber
class node_pdf_extraction,node_extraction_result toneMint
class node_job_service,node_job_repository,node_job_file_repository toneRose
```

## Components

### Web experience

- [Upload screen](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/upload/UploadScreen.tsx): `apps/web/src/components/upload/UploadScreen.tsx`
- [Progress screen](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/progress/ProgressScreen.tsx): `apps/web/src/components/progress/ProgressScreen.tsx`
- [Results screen](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/components/results/ResultsScreen.tsx): `apps/web/src/components/results/ResultsScreen.tsx`
- [Conversion context](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/context/ConversionContext.tsx): `apps/web/src/context/ConversionContext.tsx`
- [Draft file store](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/lib/fileStorage.ts): `apps/web/src/lib/fileStorage.ts`
- [Session persistence](https://github.com/amalitech-training-academy/doclift/blob/main/apps/web/src/lib/conversionSession.ts): `apps/web/src/lib/conversionSession.ts`

### Backend upload

- [Upload endpoint](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/controller/UploadController.java): `apps/backend/src/main/java/com/amalitech/backend/controller/UploadController.java`
- [Upload service](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/UploadService.java): `apps/backend/src/main/java/com/amalitech/backend/service/UploadService.java`
- [PDF validation](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfValidationService.java): `apps/backend/src/main/java/com/amalitech/backend/service/PdfValidationService.java`
- [File storage](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/FileStorageService.java): `apps/backend/src/main/java/com/amalitech/backend/service/FileStorageService.java`

### PDF analysis

- [PDF extraction](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionService.java): `apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionService.java`
- [Page extraction data](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionResult.java): `apps/backend/src/main/java/com/amalitech/backend/service/PdfExtractionResult.java`

### Job state

- [Job service](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/service/JobService.java): `apps/backend/src/main/java/com/amalitech/backend/service/JobService.java`
- [Job repository](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/repository/JobRepository.java): `apps/backend/src/main/java/com/amalitech/backend/repository/JobRepository.java`
- [Job file repository](https://github.com/amalitech-training-academy/doclift/blob/main/apps/backend/src/main/java/com/amalitech/backend/repository/JobFileRepository.java): `apps/backend/src/main/java/com/amalitech/backend/repository/JobFileRepository.java`

### Other components

- **Document user**

## Connections

- Document user → Upload screen: selects PDF
- Conversion context → Draft file store: saves and restores
- Conversion context → Session persistence: persists session
- Upload endpoint → Upload service: handles upload
- PDF extraction → Page extraction data: produces