MPVA Backend - Modular Property Verification & Acquisition

This is the backend server for the Modular Property Verification & Acquisition (MPVA) platform. The application is built with Java 17 and Spring Boot, utilizing a Modular Monolith architecture with clean, domain-driven design (DDD) principles and an Event-Driven Architecture (EDA).

🏛️ Architectural Design

Clean Architecture: Standard separation of concerns into API controllers, Application logic (DTOs, services, mappers), Domain core (entities, events), and Infrastructure (persistence, event listeners).
Modular Monolith: Each business subdomain operates as an isolated vertical slice module. Cross-module communication is asynchronous and handled through transaction-bound domain events.
JPA JOINED Inheritance: User base class uses a JOINED table inheritance scheme to model subclass variations (Buyer and Seller) in a clean, normalized relational database.

📂 Modular Structure

Module	Purpose
user	User onboarding, authentication, role and profile management (`User`, `Buyer`, `Seller`).
property	Property registration, cataloging, ownership metadata (`Property`).
verification	Core workflow tracking registry, legal, and survey checks (`VerificationRequest`).
payments	Escrow management, Paystack webhook callbacks, and refunds (`Payment`).
document	Unified attachment and validation tracking for documents (`Document`).
insurance	Risk quotes, policy management, and buyer protection (`InsurancePolicy`).
claims	Damage claims, assessment reviews, and claim settlement (`InsuranceClaim`).
trustscore	Automated risk assessment and score generation.
survey	Physical site inspections and inspector feedback tracking.
registry	Public deed and registry checks validation.
legal	Contract review, title checks, and legal reviews.
reports	PDF report compiling, QR validation, and certificate generation.
security	JWT authentication, authorization permissions, and rate-limiting.
shared	Cross-cutting concerns, base entity classes, exceptions, and event publishers.

🛠️ Technology Stack

Java 17 & Spring Boot 3
Spring Security (JWT authentication & method security)
Spring Data JPA & Hibernate
Flyway (Database migrations)
MapStruct & Lombok (DTO mappings & boilerplate elimination)
MySQL / MariaDB (Relational database)

🚀 Getting Started

Prerequisites

JDK 17 or higher
Maven 3.8+
MySQL database instance

Database Setup

Create a MySQL database called mpva.

Configure your credentials in src/main/resources/application-local.yml or using environment variables:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mpva?useSSL=false&serverTimezone=UTC
    username: your_db_username
    password: your_db_password

Flyway migrations (db/migration/V1__init_schema.sql and db/migration/V2__add_new_domain_schema.sql) will run automatically on startup to seed the tables and constraints.

Build and Run

Build the project using Maven:

mvn clean install

Start the application:

mvn spring-boot:run

The server will start by default at http://localhost:8080.

📖 API Documentation & Endpoints

Swagger UI: Accessible locally at http://localhost:8080/swagger-ui/index.html to test endpoints and view request/response schemas.
OpenAPI Docs: Schema definitions are available at http://localhost:8080/api-docs.
Endpoints List: A complete index of all exposed REST endpoints is documented in AllEndpoints.md.

MoscowDev/mpva-backend-

README