doc-flow

Java 21 · Spring Boot 3 · PostgreSQL

doc-flow

A production-shaped Spring Boot backend for asynchronous document-processing jobs. Documents flow through a managed queue — authenticated, isolated by project, tracked through every state from submission to completion.

View on GitHub ← portfolio

Job lifecycle

Queued
Submitted, waiting
Running
Being processed
Succeeded
Completed successfully
Failed
Failed, may retry
Retry
Scheduled for retry
Dead Letter
Max attempts exhausted
Cancelled
Cancelled by user

Job queue

job_a3f2...91c PDF_CONVERT QUEUED 0s ago
job_b7e1...44a IMAGE_RESIZE RUNNING · 1/3 12s ago
job_c9d4...77f OCR_EXTRACT RETRY · 2/3 2m ago
job_d2b8...12e PDF_CONVERT SUCCEEDED 5m ago
job_e5a3...33b REPORT_GEN DEAD LETTER · 3/3 18m ago

Architecture

01
JWT Authentication
Register and login with email + password. JWT tokens signed with a configurable 256-bit secret, 24h expiry by default. Spring Security validates every request.
02
Project Isolation
Each user owns projects. All resources — API keys, jobs — are scoped to a project. Users can only access their own projects, enforced at the service layer.
03
API Key Management
Projects generate hashed API keys for programmatic access. Raw key shown once on creation. Keys carry a prefix for identification and can be revoked at any time.
04
Job State Machine
7-state lifecycle with full attempt tracking. Per-attempt timestamps, outcomes, and error messages stored in job_attempts. Idempotency key support prevents duplicate submissions.

API endpoints

Auth
POST/api/auth/registerRegister a new user
POST/api/auth/loginLogin and receive JWT
Projects
POST/api/projectsCreate a project
GET/api/projectsList your projects
GET/api/projects/{id}Get project details
API Keys
POST/api/projects/{id}/keysGenerate API key — raw shown once
GET/api/projects/{id}/keysList API keys
DELETE/api/projects/{id}/keys/{keyId}Revoke an API key
Jobs
POST/api/projects/{id}/jobsSubmit a job
GET/api/projects/{id}/jobsList jobs
GET/api/projects/{id}/jobs/{jobId}Get job details
POST/api/projects/{id}/jobs/{jobId}/cancelCancel a queued or running job

Stack

Java 21 Spring Boot 3 Spring Security + JWT PostgreSQL 16 Spring Data JPA Flyway Docker Compose Maven Bean Validation
← portfolio