How kimregular/doqsa works
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: OcrStateService.java State service · OcrService.java OCR service · ImageStorage.java Image storage port · OcrItemPersistenceAdapter.java Repository adapter
Components 26
API and application
- OCR controller
backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java - OCR use case
backend/src/main/java/com/doqsa/backend/application/port/in/OcrUseCase.java - OCR service
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - API models
backend/src/main/java/com/doqsa/backend/application/model/OcrModels.java
OCR workflow
- State service
backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java - Queue dispatcher
backend/src/main/java/com/doqsa/backend/application/service/OcrDispatcher.java - Async queue
backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrQueue.java - Queue listener
backend/src/main/java/com/doqsa/backend/adapter/out/queue/OcrQueuedListener.java - Async executor
backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java - OCR processor
backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java - Lease monitor
backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java - Queue configuration
backend/src/main/java/com/doqsa/backend/global/OcrProperties.java
State and persistence
- OCR item state
backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java - Status values
backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrStatus.java - Repository adapter
backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java - JPA repository
backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemJpaRepository.java - Application database
Storage and OCR providers
- Image storage port
backend/src/main/java/com/doqsa/backend/application/port/out/ImageStorage.java - Local storage
backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java - Local upload endpoint
backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java - S3 storage
backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java - Supabase storage
backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java - Analyzer port
backend/src/main/java/com/doqsa/backend/application/port/out/OcrImageAnalyzer.java - Gemini analyzer
backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java
Other components
- API client
- Gemini API
Connections 30
- API client → OCR controller: calls API
README.md - OCR controller → OCR use case: invokes
backend/src/main/java/com/doqsa/backend/adapter/in/web/OcrController.java - OCR service → OCR use case: implements
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - OCR service → Image storage port: requests storage
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - OCR service → Repository adapter: reads and saves
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - OCR service → State service: delegates state
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - OCR service → API models: returns views
backend/src/main/java/com/doqsa/backend/application/service/OcrService.java - State service → Repository adapter: locks items
backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java - State service → Async queue: enqueues
backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java - State service → OCR item state: updates claims
backend/src/main/java/com/doqsa/backend/application/service/OcrStateService.java - State service → Queue configuration: reads settings
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
README.md - Queue listener → Async executor: forwards task
- Async executor → OCR processor: executes
backend/src/main/java/com/doqsa/backend/adapter/out/queue/SpringAsyncOcrTaskExecutor.java - OCR processor → State service: claims and completes
backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java - OCR processor → Image storage port: reads image
backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java - OCR processor → Analyzer port: requests analysis
backend/src/main/java/com/doqsa/backend/application/service/OcrProcessor.java - Lease monitor → State service: renews lease
backend/src/main/java/com/doqsa/backend/application/service/OcrLeaseMonitor.java - Repository adapter → JPA repository: delegates persistence
backend/src/main/java/com/doqsa/backend/adapter/out/persistence/OcrItemPersistenceAdapter.java - JPA repository → OCR item state: loads entities
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
backend/src/main/java/com/doqsa/backend/domain/ocritem/OcrItem.java - Image storage port → Local storage: implemented by
backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageStorage.java - Image storage port → S3 storage: implemented by
backend/src/main/java/com/doqsa/backend/adapter/out/storage/s3/S3ImageStorage.java - Image storage port → Supabase storage: implemented by
backend/src/main/java/com/doqsa/backend/adapter/out/storage/supabase/SupabaseImageStorage.java - Local upload endpoint → Local storage: accepts upload
backend/src/main/java/com/doqsa/backend/adapter/out/storage/local/LocalImageController.java - Analyzer port → Gemini analyzer: implemented by
backend/src/main/java/com/doqsa/backend/adapter/out/ocr/GeminiOcrImageAnalyzer.java - Gemini analyzer → Gemini API: calls API