Library Management System | Spring Backend

CoolLib — Containerized Library Ecosystem: A Clean Architecture Implementation

Spring Boot Cloudflare D1 Workers Docker Nginx PostgreSQL R2 Storage Kotlin

A high-performance distributed system built on Clean Architecture, with a Dockerized backend orchestrating core business logic via Spring Boot and PostgreSQL. The architecture leverages Cloudflare D1 for edge-side persistence of telemetry, while Workers provide a reactive observability layer. Secure, zero-trust connectivity is maintained via Cloudflare Tunnels, delivering a seamless experience to Android (Compose) and iOS (SwiftUI) clients.

Source Code
CI/CD

Project Overview

CoolLib Backend is a mission-critical RESTful service built with Spring Boot and Kotlin. Beyond standard CRUD, it orchestrates complex business state machines and implements Cloudflare-native infrastructure to ensure global low-latency data synchronization and secure asset management across the mobile ecosystem.

Key Technical Wins

Clean Architecture

Adheres to Clean Architecture and DDD principles. It maintains a pure domain model by strictly decoupling JPA Entities from API DTOs via custom mapping layers, preventing database leakage into the presentation tier.

Edge Persistence & D1

Implements Cloudflare D1 as a globally distributed SQLite layer. It offloads high-frequency telemetry and health metrics from the primary PostgreSQL instance, ensuring the core database remains optimized for ACID-compliant transactions.

Stateless Security & Tunnels

Orchestrates Spring Security + JWT for stateless, mobile-first authentication. The backend origin is shielded by Cloudflare Tunnels, eliminating public entry points and ensuring a Zero-Trust connectivity model.

Reactive Observability Pipeline

Engineered an observability stack using Cloudflare Workers to intercept and analyze traffic patterns in real-time. This provides instant insights into API performance without introducing latency to the Spring Boot origin.

System Architecture

Architecture Design
flowchart LR subgraph Clients ["`**Clients**`"] A(Android Compose) B(iOS SwiftUI) end subgraph CF1 ["`**Cloudflare Edge (Delivery)**`"] G1{CDN Cache} R2[(R2 Storage)] C{Tunnel} end subgraph CF2 ["`**Cloudflare Observability**`"] W(Worker Monitor) D1[(D1 Metrics)] MON(Monitor Dashboard) end subgraph Docker ["`**Docker Infrastructure**`"] D(Nginx Proxy) E(Spring Boot) H[(Postgre SQL)] end %% ========================= %% FLOW %% ========================= A e1@--> G1 B e2@--> G1 G1 -- "Static Assets" --> R2 G1 -- "API Requests" --> C C e3@--> D D --> E E --> H %% Observability (clean separation) E e4@--> W W --> D1 D1 --> MON W --> MON %% ========================= %% animations %% ========================= e1@{ animation: slow } e2@{ animation: slow } e3@{ animation: slow } e4@{ animation: slow } %% ========================= %% CLIENT LAYER (brand light) %% ========================= style A fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff style B fill:#0A84FF,stroke:#0066cc,stroke-width:2px,color:#fff %% ========================= %% CLOUDFLARE LAYER (unified blue system) %% ========================= style G1 fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff style C fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff style R2 fill:#60a5fa,stroke:#3b82f6,stroke-width:1px,color:#fff %% ========================= %% OBSERVABILITY (light blue system) %% ========================= style W fill:#93c5fd,stroke:#3b82f6,stroke-width:2px,color:#fff style D1 fill:#bfdbfe,stroke:#60a5fa,stroke-width:1px,color:#fff style MON fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff %% ========================= %% BACKEND (UNIFIED SYSTEM COLOR) %% Nginx + Spring + PostgreSQL = ONE SYSTEM %% ========================= style D fill:#64748b,stroke:#334155,stroke-width:2px,color:#fff style E fill:#475569,stroke:#334155,stroke-width:2px,color:#fff style H fill:#334155,stroke:#334155,stroke-width:2px,color:#fff style Clients fill:#f8fafc style CF1 fill:#f1f5f9 style CF2 fill:#f8fafc style Docker fill:#f1f5f9 %% ========================= %% LINKS %% ========================= linkStyle default stroke:#94a3b8,stroke-width:1.5px

Cloudflare Edge-secured system with Dockerized backend and real-time observability.

Security & Acceleration Strategy

Hybrid Security & Caching Architecture

Distributed authentication with edge-level performance optimization.

Stateless JWT Edge Caching Zero-Trust Tunnel
sequenceDiagram autonumber participant User as Mobile Client participant Edge as Cloudflare Edge participant Origin as Spring Boot (Origin) participant DB as PostgreSQL Note over User, DB: Phase 1: Secure Identity Issuance User->>Edge: POST /api/auth/login Note right of Edge: WAF Filtering & Tunneling Edge->>Origin: Forward to Private Network Origin->>DB: BCrypt Credential Verify DB-->>Origin: Record Found Origin-->>User: 200 OK (JWT Access Token) Note over User, DB: Phase 2: Accelerated Data Access User->>Edge: GET /api/books (Header: Bearer) alt Cache Hit (Global Edge Node) Edge-->>User: 200 OK (Instant Cached JSON) else Cache Miss (Secure Fetch) Edge->>Origin: Tunnel Forward Origin->>Origin: OncePerRequestFilter (JWT Check) Origin->>DB: Fetch Library Data DB-->>Origin: ResultSet Origin-->>Edge: Response + Cache-Control Edge-->>User: 200 OK (Fresh Data) end
Architectural Highlights
  • Latency Reduction: Read-heavy endpoints (like book search) are cached at 300+ global edge locations.
  • Zero Public Ports: The Spring Boot server remains invisible to the public internet via Cloudflare Tunnel.
  • Separation of Concerns: Security is handled at the Origin (JWT), while delivery is optimized at the Edge.

Tech Stack

  • Core Framework: Spring Boot 3.x, Kotlin, Gradle
  • Edge Infrastructure: Cloudflare D1 (SQL), Workers, R2 (S3 Storage), Tunnels
  • Data & Security: PostgreSQL, Spring Data JPA, JWT, Spring Security
  • DevOps: Docker, Nginx, GitHub Actions (CI/CD)

Core Features

Advanced Search

Transaction Logic

Deployment Stack

Method Endpoint Description Auth
POST /api/auth/login Verify credentials and issue a JWT Access Token.
POST /api/borrow/scan Process borrowing via Barcode/ISBN scan. In Dev
GET /api/stats/loans Fetch aggregate data of active loans and trends. Planned
GET /api/users/profile Retrieve identity claims from the decrypted JWT payload.
GET /api/auth/validate Check if the current token is expired or blacklisted.
Method Endpoint Description Auth
GET /api/books/search Multi-criteria filtering by Title, Author, Publisher, and Year.
GET /api/books/fuzzy Fuzzy search using Levenshtein Distance or partial matching logic. In Dev
GET /api/books/recommend Content-based filtering using User Borrowing History. Planned
GET /api/books/isbn/{isbn} Direct lookup via 10 or 13-digit International Standard Book Number.
Transaction Processing Pipeline
ACID SECURE
Identity Authorization
Extract userId & roles from JWT claims.
Concurrency Locking
Execute SELECT FOR UPDATE to prevent race conditions.
Business Validation
Verify stock availability and user borrow limits.
Atomic Commit
Persist LoanRecord & update Inventory.

Managed by Spring @Transactional logic.

Security
Zero-Trust Tunnel

Utilizing Cloudflare Tunnels to expose the API via encrypted outbound connections, eliminating attack surfaces and public-facing ports.

Performance
Edge & R2 Storage

Offloading media to Cloudflare R2 with zero egress fees, combined with Edge Caching to deliver assets at millisecond speeds.

DevOps
Docker Orchestration

Encapsulating Spring Boot, Nginx, and Postgres within Docker Compose for consistent environments and automated deployment.

Flow
Traffic Architecture
Static Edge → R2 Bucket
Dynamic Tunnel → Nginx → Spring

Developed with passion by Ryan Su © 2026