Nucleus Framework

Production-ready microservices foundation for Java / Spring Boot

Nucleus is a modular platform layer that provides the infrastructure every enterprise microservices application needs -- authentication, audit trails, messaging, monitoring, email, storage, and more. Add it as a Maven dependency and start building business logic on day one.

Quick Start

1. Add the parent POM

<parent>
    <groupId>com.nucleus</groupId>
    <artifactId>nucleus-parent</artifactId>
    <version>0.0.1</version>
</parent>

2. Pick your modules

<dependencies>
    <dependency>
        <groupId>com.nucleus</groupId>
        <artifactId>nucleus-core</artifactId>
        <version>0.0.1</version>
    </dependency>
    <dependency>
        <groupId>com.nucleus</groupId>
        <artifactId>nucleus-audit-core</artifactId>
        <version>0.0.1</version>
    </dependency>
</dependencies>

3. Configure

spring:
  config:
    import: configserver:https://your-config-server
  application:
    name: my-service
  profiles:
    active: monitoring

Architecture

nucleus-parent (Maven parent POM)
  nucleus-bom (Bill of Materials)

nucleus-core (foundation: security, JWT, pagination, reports)
  nucleus-connectors (Kafka messaging abstraction)
    nucleus-monitoring-client (self-registration, remote logging)
  nucleus-audit-core (@AuditAction declarative audit)
  nucleus-storage (MinIO/S3 file storage)
  nucleus-execution-events (async job framework)
  nucleus-authentication (OAuth2/OIDC server)

nucleus-mail-common (shared DTOs)
  nucleus-mail (rendering + sending + step tracking)
  nucleus-mail-renderer (Thymeleaf template engine)
  nucleus-mail-sender (SMTP delivery)

nucleus-ui-message-broker (SSE with role-based delivery)
nucleus-config (Spring Cloud Config Server)
nucleus-user (user management + roles)
nucleus-address (Google Maps integration)

nucleus-core

Foundation

The base layer every Nucleus service extends. Provides security filters, JWT validation, pagination, error handling, and report generation.

• BaseComponent -- base class with common utilities (dialog, navigation, error handling)
• JWT Security -- automatic JWT validation via Spring Security resource server
• Pagination -- generic Page, PageResult, SearchService interfaces
• Report Generation -- PDF, Excel, CSV export with built-in file viewer
• Permission Checker -- role-based access utilities

nucleus-authentication

Security

Full OAuth2/OIDC authorization server built on Spring Authorization Server.

• JWT tokens with RSA rotating keys
• Login/logout audit trail
• Role-based access (ROLE_ADMIN, ROLE_CLIENT, ROLE_AUDITOR, etc.)
• Configurable token expiry
• Branded login page with Thymeleaf templates

nucleus-audit-core

Compliance

Add audit trails to any service method with a single annotation.

@AuditAction(
    action = "Update Expense",
    entityName = "Expense",
    description = "Updated expense #{#result.id} for #{#result.vendor}"
)
public Expense updateExpense(ExpenseDTO dto) { ... }

• SpEL expressions for dynamic descriptions
• Automatically captures username, timestamp, entity ID
• Published to Kafka for real-time audit dashboards
• Stored in audit database with full history

nucleus-connectors

Messaging

Pluggable messaging abstraction. Currently backed by Apache Kafka, designed for multiple backends.

• Publisher -- @MiddlewareQualifier(type = KAFKA) for transactional, transactional = false for fire-and-forget
• Listener -- kafkaConnector.createListener(topic, handler)
• Serialization -- @MessageFormatQualifier for JSON, XML, YAML, Text
• Swap messaging backend by changing the @MiddlewareQualifier annotation -- no code changes required
• Add new backends by implementing the Connector interface (Kafka ships out of the box, RabbitMQ support planned)

nucleus-monitoring-client

Observability

Lightweight service monitoring. Add the dependency, enable the monitoring profile, and your service self-registers.

Remote Logging Setup

Add to logback-spring.xml:

<appender name="REMOTE" class="com.nucleus.monitoring.client.KafkaLogAppender" />
<root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="REMOTE" />
</root>

The appender is inactive by default. Toggle at runtime via the REST endpoint. All endpoints require ROLE_ADMIN.

nucleus-ui-message-broker

Real-time

Server-Sent Events (SSE) with role-based delivery for real-time UI updates.

• Single SSE endpoint per user -- multiplexes all message types
• Role-based targeting: send to ROLE_ADMIN, specific users, or broadcast
• Message expiration -- stale messages auto-expire
• Used for: service health, job progress, notifications, live dashboards

nucleus-mail

Communication

Kafka-driven email pipeline with three stages: render, send, track.

• nucleus-mail-common -- shared DTOs for publishing mail requests
• nucleus-mail -- unified library: rendering + sending + tracking
• nucleus-mail-renderer -- Thymeleaf template engine
• nucleus-mail-sender -- SMTP delivery with retry
• Full delivery tracking: queued, rendered, sent, delivered, failed
• Resend capability via REST endpoint

nucleus-storage

Storage

MinIO/S3-compatible object storage abstraction.

• Upload, download, delete with standardized paths
• Path pattern: {clientId}/{entityId}/filename.ext
• Pluggable backend -- swap MinIO for AWS S3

nucleus-execution-events

Processing

Async job execution framework for long-running processes.

• Job / Step / Activity lifecycle events via Kafka
• Real-time progress updates pushed to UI via SSE
• Persisted in database for history and reporting

nucleus-config

Configuration

Spring Cloud Config Server backed by MySQL database.

• All services pull configuration at startup
• Change config without redeployment
• Environment-specific profiles
• Encrypted properties for secrets

nucleus-user

Identity

User management, role assignment, and access request workflows.

nucleus-address

Integration

Google Maps Places API integration for address autocomplete and validation.

Dependency Map

nucleus-parent  -->  nucleus-bom
nucleus-bom     -->  All modules (version management)

nucleus-core  -->  nucleus-connectors
              -->  nucleus-storage
              -->  nucleus-audit-core
              -->  nucleus-authentication
              -->  nucleus-execution-events

nucleus-connectors  -->  nucleus-monitoring-client
                    -->  nucleus-ui-message-broker

nucleus-mail-common  -->  nucleus-mail
                     -->  nucleus-mail-renderer
                     -->  nucleus-mail-sender

nucleus-audit-core  -->  All application services (transitive)

Configuration Properties

Tech Stack