DATA MANAGEMENT SERVICE

A private Spring Boot REST API designed for data management across the ecosystem. It uses a multi-tenant architecture to isolate data between different clients/tenants securely.

Instead of managing ecosystem data (like products and categories) through manual SQL scripts, this service provides endpoints to create and manage these records dynamically.

Why?

• Built with industry-standard OAuth2 and JWT validation + strict code-level permission checks. You won't have to worry about unauthorized access or security gaps.
• Features automated multi-tenancy that safely separates data for different users behind the scenes. Tenants will never accidentally (or intentionally) see each other's information.
• Instead of dealing with messy manual database scripts every time products or categories change, this provides clean, dynamic endpoints to manage data instantly.
• With advanced database configuration (like turning off Open-in-View(OSIV) to protect connection pools and using PostgreSQL for safe rollbacks), the service stays fast and stable even under heavy traffic. Additionally, automated audit logging tracks who did what and when.
• Fully documented with interactive Swagger UI and clear code comments, meaning any future developer can jump in, understand how it works and start building immediately without a steep learning curve.

Latest Features

• Added endpoints to archive, restore, or permanently delete records.

Key Features

• OAuth2 Resource Server: Secures endpoints out-of-the-box by validating incoming JWTs against the identity provider using the configured jwk-set-uri.
• Multi-Tenancy: Automatically pulls the tenant-id claim from the user's JWT and binds it to a request-scoped ThreadLocal context so tenants never cross paths.
• Audit Logging: Keeps track of who did what and when by automatically populating created_by, updated_by, created_at and updated_at fields on the entities.
• Method-Level Security: Secures business logic directly at the code level using Spring Security annotations like @PreAuthorize based on token claims and roles.
• Swagger/OpenAPI Documentation: Comes with interactive API docs generated automatically, making it easy to test endpoints right in the browser.
• Javadocs: Well-documented codebase with clear JavaDoc comments explaining core custom filters, resources, services, domain models, etc.

Technology Stack

• Database: PostgreSQL
• Migration Tool: Liquibase
• Security: Spring Security (OAuth2 Resource Server via JWT validation)
• Documentation: springdoc-openapi v2.7.0 (Swagger UI available in development)
• Shared Infrastructure: shared-service (Internal dependency for re-usable domains, global exception handling, and custom validation groups)

Decision Log (Architecture Decision Records)

ADR 1: PostgreSQL over MySQL

• Decision: Chose PostgreSQL as the primary relational database for this service's data hierarchy.
• Rationale:
  • Transactional DDL: Liquibase migrations execute safely. If a migration fails midway, PostgreSQL rolls back the entire schema change automatically (avoiding MySQL's risk of leaving the database in a partially broken state).
  • JSONB Support: Offers native, highly indexable JSON querying for flexible, semi-structured referential properties.
  • Index Efficiency: Provides optimized B-Tree indexing models that reduce RAM and storage overhead during heavy read operations.

ADR 2: OSIV Disabled (spring.jpa.open-in-view: false)

• Decision: Restrict database connection streams to remain open exclusively during active database transactions.
• Rationale:
  • Streamlines the request/response lifecycle and prevents connection pool starvation under heavy load.
  • DTO mapping must occur strictly inside transactional boundaries to prevent LazyInitializationException issues.

ADR 3: Domain Identity via my_key

• Decision: Separate physical database auto-increment/sequence IDs from logical domain keys.
• Rationale:
  • Ensures identity stability and reliable data mapping across cross-environment migrations, staging syncs and distributed state replication.

Support

• Liquibase Migration Failures:

  • Symptom: Migration failed for change set or application crashes instantly at boot.
  • Fix: Verify that raw SQL changesets have valid headers (--liquibase formatted sql). If manual testing dirtied the metadata tracking schema, verify the status of the DATABASECHANGELOG tracking table directly.

• Cross-Tenant Access Issue:

  • Symptom: API requests return empty arrays ([]) or 404 Not Found, even though the data exists in the database.
  • Fix: Verify that the global tenant filter is active and correctly capturing the tenant-id of the currently logged-in user. If testing locally, ensure development mode is enabled so the application properly handles mock or local tenant contexts. If dev-mode is misconfigured, the filter might default to a tenant ID that doesn't contain the test data.

Future Enhancements

• Library Migration: Decouple and migrate global infrastructure pieces (TenantFilter, JwtAuthenticationConverter and OpenAPI config) directly into a library to keep this business microservice lightweight.
• Smart Updates: Transition updating logic from being solely field-name-based to utilizing a structured system key (my_key), enabling safer modifications including all field renames.

Check out the Tenant Isolation, RBAC and Archive Features demo video to see a live demonstration of multi-tenant data separation, role-based access enforcement and the soft-delete/archive lifecycle in action.