# kimregular/doqsa architecture

> Architecture diagram of the GitHub repository kimregular/doqsa, 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/kimregular/doqsa
- Repository: https://github.com/kimregular/doqsa

## Overview

DOQSA is a Spring backend for uploading receipt images, queueing asynchronous OCR, and retrieving task status and extracted results. The main flow is REST request → item and upload URL creation → upload confirmation and queueing → claimed OCR processing → persisted result or retry/failure → status/result retrieval. Storage and OCR providers are pluggable. The README documents lease recovery, polling, and provider options; some runtime classes were not sampled, so those links are marked unverified rather than asserted as inspected.

Main entry points: [`backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java) (State service), [`backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrService.java) (OCR service), [`backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java`](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java) (Image storage port), [`backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java`](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java) (Repository adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and application"]
  node_controller["OCR controller<br/>[OcrController.java]"]
  node_usecase["OCR use case<br/>[OcrUseCase.java]"]
  node_service["OCR service<br/>[OcrService.java]"]
  node_models["API models<br/>[OcrModels.java]"]
end

subgraph group_workflow["OCR workflow"]
  node_state["State service"]
  node_dispatcher["Queue dispatcher<br/>[OcrDispatcher.java]"]
  node_queue["Async queue"]
  node_listener["Queue listener"]
  node_executor["Async executor"]
  node_processor["OCR processor<br/>[OcrProcessor.java]"]
  node_lease["Lease monitor"]
  node_ocrproperties["Queue configuration<br/>[OcrProperties.java]"]
end

subgraph group_persistence["State and persistence"]
  node_domain["OCR item state<br/>[OcrItem.java]"]
  node_status["Status values<br/>[OcrStatus.java]"]
  node_repository["Repository adapter"]
  node_jpa["JPA repository"]
  node_database[("Application database")]
end

subgraph group_integrations["Storage and OCR providers"]
  node_storageport["Image storage port<br/>[ImageStorage.java]"]
  node_localstorage["Local storage"]
  node_localupload["Local upload endpoint"]
  node_s3storage["S3 storage"]
  node_supabasestorage["Supabase storage"]
  node_analyzerport["Analyzer port"]
  node_gemini["Gemini analyzer"]
end

node_client(("API client"))
node_geminiservice{{"Gemini API"}}

node_client -->|"calls API"| node_controller
node_controller -->|"invokes"| node_usecase
node_service -->|"implements"| node_usecase
node_service -->|"requests storage"| node_storageport
node_service -->|"reads and saves"| node_repository
node_service -->|"delegates state"| node_state
node_service -->|"returns views"| node_models
node_state -->|"locks items"| node_repository
node_state -->|"enqueues"| node_queue
node_state -->|"updates claims"| node_domain
node_state -->|"reads settings"| node_ocrproperties
node_dispatcher -.->|"scans runnable"| node_repository
node_dispatcher -.->|"submits work"| node_executor
node_queue -.->|"dispatches event"| node_listener
node_listener -.->|"forwards task"| node_executor
node_executor -->|"executes"| node_processor
node_processor -.->|"claims and completes"| node_state
node_processor -.->|"reads image"| node_storageport
node_processor -.->|"requests analysis"| node_analyzerport
node_lease -.->|"renews lease"| node_state
node_repository -->|"delegates persistence"| node_jpa
node_jpa -->|"loads entities"| node_domain
node_repository -.->|"reads and writes"| node_database
node_domain -->|"uses statuses"| node_status
node_storageport -->|"implemented by"| node_localstorage
node_storageport -->|"implemented by"| node_s3storage
node_storageport -->|"implemented by"| node_supabasestorage
node_localupload -->|"accepts upload"| node_localstorage
node_analyzerport -->|"implemented by"| node_gemini
node_gemini -.->|"calls API"| node_geminiservice

click node_controller "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java"
click node_usecase "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/in/OcrUseCase.java"
click node_service "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrService.java"
click node_models "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/model/OcrModels.java"
click node_state "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java"
click node_dispatcher "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrDispatcher.java"
click node_queue "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrQueue.java"
click node_listener "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/OcrQueuedListener.java"
click node_executor "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java"
click node_processor "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java"
click node_lease "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java"
click node_domain "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java"
click node_status "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrStatus.java"
click node_repository "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java"
click node_jpa "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemJpaRepository.java"
click node_storageport "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java"
click node_localstorage "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java"
click node_localupload "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java"
click node_s3storage "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java"
click node_supabasestorage "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java"
click node_analyzerport "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/out/OcrImageAnalyzer.java"
click node_gemini "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java"
click node_ocrproperties "https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/global/OcrProperties.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_controller,node_usecase,node_service,node_models,node_client toneBlue
class node_state,node_dispatcher,node_queue,node_listener,node_executor,node_processor,node_lease,node_ocrproperties toneAmber
class node_domain,node_status,node_repository,node_jpa,node_database,node_geminiservice toneMint
class node_storageport,node_localstorage,node_localupload,node_s3storage,node_supabasestorage,node_analyzerport,node_gemini toneRose
```

## Components

### API and application

- [OCR controller](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java): `backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java`
- [OCR use case](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/in/OcrUseCase.java): `backend/src/main/java/com/doqsa/backend/application/port/in/OcrUseCase.java`
- [OCR service](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrService.java): `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`
- [API models](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/model/OcrModels.java): `backend/src/main/java/com/doqsa/backend/application/model/OcrModels.java`

### OCR workflow

- [State service](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java): `backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`
- [Queue dispatcher](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrDispatcher.java): `backend/src/main/java/com/doqsa/backend/application/service/OcrDispatcher.java`
- [Async queue](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrQueue.java): `backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrQueue.java`
- [Queue listener](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/OcrQueuedListener.java): `backend/src/main/java/com/doqsa/backend/adapter/out/queue/OcrQueuedListener.java`
- [Async executor](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java): `backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java`
- [OCR processor](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java): `backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java`
- [Lease monitor](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java): `backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java`
- [Queue configuration](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/global/OcrProperties.java): `backend/src/main/java/com/doqsa/backend/global/OcrProperties.java`

### State and persistence

- [OCR item state](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java): `backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java`
- [Status values](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrStatus.java): `backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrStatus.java`
- [Repository adapter](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java): `backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java`
- [JPA repository](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemJpaRepository.java): `backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemJpaRepository.java`
- **Application database**

### Storage and OCR providers

- [Image storage port](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java): `backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java`
- [Local storage](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java): `backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java`
- [Local upload endpoint](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java): `backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java`
- [S3 storage](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java): `backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java`
- [Supabase storage](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java): `backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java`
- [Analyzer port](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/application/port/out/OcrImageAnalyzer.java): `backend/src/main/java/com/doqsa/backend/application/port/out/OcrImageAnalyzer.java`
- [Gemini analyzer](https://github.com/kimregular/doqsa/blob/main/backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java): `backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java`

### Other components

- **API client**
- **Gemini API**

## Connections

- API client → OCR controller: calls API (evidence: `README.md`)
- OCR controller → OCR use case: invokes (evidence: `backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java`)
- OCR service → OCR use case: implements (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`)
- OCR service → Image storage port: requests storage (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`)
- OCR service → Repository adapter: reads and saves (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`)
- OCR service → State service: delegates state (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`)
- OCR service → API models: returns views (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrService.java`)
- State service → Repository adapter: locks items (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`)
- State service → Async queue: enqueues (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`)
- State service → OCR item state: updates claims (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`)
- State service → Queue configuration: reads settings (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java`)
- Queue dispatcher → Repository adapter: scans runnable
- Queue dispatcher → Async executor: submits work
- Async queue → Queue listener: dispatches event (evidence: `README.md`)
- Queue listener → Async executor: forwards task
- Async executor → OCR processor: executes (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java`)
- OCR processor → State service: claims and completes (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java`)
- OCR processor → Image storage port: reads image (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java`)
- OCR processor → Analyzer port: requests analysis (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java`)
- Lease monitor → State service: renews lease (evidence: `backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java`)
- Repository adapter → JPA repository: delegates persistence (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java`)
- JPA repository → OCR item state: loads entities (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemJpaRepository.java`)
- Repository adapter → Application database: reads and writes
- OCR item state → Status values: uses statuses (evidence: `backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java`)
- Image storage port → Local storage: implemented by (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java`)
- Image storage port → S3 storage: implemented by (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java`)
- Image storage port → Supabase storage: implemented by (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java`)
- Local upload endpoint → Local storage: accepts upload (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java`)
- Analyzer port → Gemini analyzer: implemented by (evidence: `backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java`)
- Gemini analyzer → Gemini API: calls API
