# Property Tax Architecture

### Overview

The DIGIT Property Tax module implements a microservices architecture with clearly defined core services, common services, and reusable components. The system follows event-driven patterns using Kafka for asynchronous processing and maintains data consistency through well-defined service interactions.

The Property Tax module consists of three main microservices:

1. property services - Legacy property management services
2. pt-services-v2 - Modern property management services
3. pt-calculator-v2 - Billing and tax calculation service

```
property-tax/
├── property-services/       # Legacy property management service
├── pt-services-v2/         # Modern property management service (V2)
└── pt-calculator-v2/       # Billing and tax calculation service (V2)
```

## 1. **property-services** - Legacy Property Management Service

The original property management service that handles comprehensive property data management, including:

* Property master data management
* Owner and institutional ownership tracking
* Property addresses with geolocation support
* Unit/floor-level details
* Property assessments for each financial year
* Document management (property documents, owner documents, assessment documents)
* Draft property submissions
* Property migration tracking
* Data encryption audit trails

**Key Features:**

* Complete CRUD operations for properties and assessments
* Support for both individual and institutional ownership
* Multi-unit/floor property support
* Comprehensive address management with GPS coordinates
* Financial year-based assessments
* Full audit trail through dedicated audit tables
* Property migration support from legacy systems
* Data encryption capabilities

## 2. **pt-services-v2** - Property Management Service V2

Modern redesigned service for property tax management with improved data structure:

* Streamlined property registration and management
* Enhanced owner information management
* Improved address and geolocation tracking
* Property detail and assessment management
* Unit-level property management
* Document management for properties and owners
* Institutional ownership support
* Draft property submissions
* Comprehensive audit trails

**Key Features:**

* Simplified and efficient data model
* JSONB support for flexible additional data
* Enhanced indexing for better performance
* Support for ad-hoc exemptions and penalties
* Improved multi-tenancy support
* Financial year-based property details
* Annual Rental Value (ARV) tracking
* Construction type and usage category management

#### 3. **pt-calculator-v2** - Tax Calculation Service V2

Specialised service handling all property tax calculations and billing:

* Billing slab configuration based on multiple property parameters
* Property tax calculation using configurable rate structures
* Mutation fee calculation for ownership transfers
* Assessment record management
* Dynamic rate determination based on:
  * Property type and subtype
  * Usage categories (Major/Minor/Sub-minor/Detail)
  * Ownership categories
  * Floor levels
  * Plot size ranges
  * Occupancy type
  * Area type
  * Market value (for mutation fees)

**Key Features:**

* Flexible multi-parameter billing slab system
* Support for unit rate and ARV percentage-based calculations
* Unbuilt land tax calculation
* Mutation fee calculation with fixed and percentage methods
* Market value-based fee determination
* Assessment of demand linking
* Tenant-specific rate configuration
* Multi-floored property support

## Technology Stack

* **Framework:** Spring Boot (Java 8+)
* **Database:** PostgreSQL 9.6+
* **Migration Tool:** Flyway
* **Data Formats:** JSON/JSONB for flexible data storage
* **Architecture:** Microservices-based
* **Multi-tenancy:** Supported across all services

## Module Package Structure

The Property Tax module follows DIGIT’s layered, event-driven architecture with a clear separation of responsibilities across packages. This makes the codebase easier to understand, navigate, and maintain.

Configuration is kept in **config**, business logic in **service**, utilities and constants in **util**, and validations in **validator**. Data access and external integrations are handled by the **repository**, with a **builder** for queries and a **rowmapper** for mapping database results. The **web** layer exposes APIs through **controllers** and defines request/response objects in **models**, while Kafka-based messaging is managed through **consumer** and **producer** packages.

```
config - Contains all the configuration properties related to the module
service - Consists of all services containing the business logic.
util - Contains utility functions and constants.
validator - Contains all validation code
repository - Fetch data from dependent micro services
repository/rowmapper - Rowmappers to convert db query results to object
repository/builder - Contains query builder for search
web/controllers - Controllers for the app.
web/models - POJO for the module.
consumer - Contains all the Kafka consumers,
producer - Contains kafka producer
```

The Property Tax Calculator module follows DIGIT’s event-driven microservices architecture. Its package structure separates messaging, data access, business logic, and configuration, making the codebase easier to understand and maintain.

Kafka interactions are handled through dedicated **consumers** and **producers**, database access is managed by **repository** and **query-builder** packages, domain data is defined in **models**, and all service and infrastructure settings are grouped under **config**.

```
property-tax-calculator/
├── consumer/           # Message queue consumers
├── producer/           # Message queue producers
├── repository/         # Data access layer
├── query-builder/      # Query construction utilities
├── models/            # Data models and entities
└── config/            # Configuration files
```

### Core Components

The core components encapsulate the key business workflows of the module. Listed below are the key components used by the module.

* **Calculator Service:** Implements property tax calculation rules
* **Demand Service:** Manages demand creation and updates
* **Billing Integration:** Interfaces with the billing service
* **Finance Integration:** Posts transactions to the finance system
* **Notification Service:** SMS and email notifications to citizens and officials at relevant stages