🎓 Certificate Generation System

A multi-tenant backend system for issuing, managing, and publicly verifying digital certificates — built with Spring Boot 3.4, Spring Security (JWT), PostgreSQL, and OpenPDF.

Organizations register, define courses with eligibility rules, enroll recipients, assign signatories, and generate branded PDF certificates — all through a secured REST API.

System Architecture

Request Lifecycle

Every API call flows through a consistent layered pipeline:

sequenceDiagram
    participant C as Client
    participant F as JwtAuthFilter
    participant CT as Controller
    participant S as Service
    participant R as Repository
    participant DB as PostgreSQL
    participant EH as GlobalExceptionHandler

    C->>F: HTTP Request + Bearer Token
    F->>F: Extract & validate JWT
    F->>F: Load OrganizationPrincipal
    F->>CT: Authenticated request

    CT->>S: Delegate business logic
    S->>R: Data access
    R->>DB: Query / Persist
    DB-->>R: Result
    R-->>S: Entity
    S-->>CT: Response DTO
    CT-->>C: HTTP 2xx + JSON

    Note over S,EH: On failure
    S--xEH: Throws domain exception
    EH-->>C: Structured error response

Domain Model

Security Architecture

Key security decisions:

Package Structure

src/main/java/com/niranjan/certificates/
├── CertificatesGenerationApplication.java    # Spring Boot entry point
├── controller/
│   ├── AuthController.java                   # Login, register, refresh
│   ├── OrganizationController.java           # Org profile & logo
│   ├── CourseController.java                 # Course CRUD
│   ├── RecipientController.java              # Recipient CRUD
│   ├── SignatoryController.java              # Signatory CRUD + signature upload
│   └── CertificateController.java           # Generate, list, download, verify
├── dto/
│   ├── request/                              # Validated input payloads
│   │   ├── LoginRequest, RegisterRequest
│   │   ├── CourseRequest, RecipientRequest
│   │   ├── CertificateRequest, SignatoryRequest
│   │   ├── UpdateOrgRequest, ListQuery
│   │   └── RefreshTokenRequest
│   └── response/                             # Output payloads
│       ├── AuthResponse, OrganizationResponse
│       ├── CourseResponse, RecipientResponse
│       ├── CertificateResponse, SignatoryResponse
│       ├── VerifyResponse, PageResponse
│       └── ...
├── entity/
│   ├── Organization.java                     # Tenant root entity
│   ├── Course.java                           # Course with minScore eligibility
│   ├── Recipient.java                        # Enrolled learner
│   ├── Signatory.java                        # Certificate signer
│   ├── Certificate.java                      # Issued certificate
│   └── CertificateStatus.java               # ISSUED / REVOKED enum
├── exception/
│   ├── GlobalExceptionHandler.java           # Centralized error responses
│   ├── ResourceNotFoundException.java
│   ├── DuplicateResourceException.java
│   └── IneligibleRecipientException.java
├── repository/
│   ├── OrganizationRepository.java
│   ├── CourseRepository.java
│   ├── RecipientRepository.java
│   ├── SignatoryRepository.java
│   └── CertificateRepository.java
├── security/
│   ├── SecurityConfig.java                   # Filter chain & endpoint rules
│   ├── JwtAuthenticationFilter.java          # Per-request token validation
│   ├── JwtService.java                       # Token creation & parsing
│   ├── AuthSessionService.java               # Refresh token rotation
│   ├── OrganizationPrincipal.java            # Authenticated identity
│   └── OrganizationUserDetailsService.java   # UserDetailsService impl
└── service/
    ├── CertificateService.java               # Interface
    ├── CourseService.java
    ├── RecipientService.java
    ├── SignatoryService.java
    ├── OrganizationService.java
    ├── PdfService.java
    ├── ImageService.java
    ├── FileStorageService.java
    └── impl/
        ├── CertificateServiceImpl.java       # Core cert logic + PDF orchestration
        ├── CourseServiceImpl.java             # Soft delete, minScore defaults
        ├── RecipientServiceImpl.java          # Post-issuance guards
        ├── SignatoryServiceImpl.java          # Default signatory management
        ├── OrganizationServiceImpl.java       # Profile & logo management
        ├── PdfServiceImpl.java               # OpenPDF rendering engine
        ├── ImageServiceImpl.java             # PDF-to-image conversion
        └── FileStorageServiceImpl.java       # Local disk I/O

Tech Stack

API Overview

Public Endpoints

Protected Endpoints (Bearer token required)

Business Rules

Certificate Issuance Guards

• Recipient and signatory must belong to the authenticated organization
• Recipient's course must be active
• Recipient's score must meet or exceed the course minScore
• Only one certificate per organization–recipient pair (enforced in code + DB constraint)
• Failed DB writes trigger best-effort PDF cleanup

Recipient Protection

• Course cannot be changed after a certificate has been issued
• Recipient cannot be deleted after a certificate has been issued
• Course must be active at the time of creation or update

Course Lifecycle

• Courses are soft-deleted (marked inactive) to preserve historical certificates
• minScore defaults to 0 when omitted; validated in range [0, 100]

Error Handling

All errors are normalized through GlobalExceptionHandler into a consistent response shape:

{
  "status": 404,
  "message": "Resource not found",
  "timestamp": "2026-04-26T00:30:00"
}

Design Decisions