Skip to content

ARCHITECTURAL_BLUEPRINT.md

Latest commit

 

History

History
156 lines (121 loc) · 5.19 KB

ARCHITECTURAL_BLUEPRINT.md

File metadata and controls

156 lines (121 loc) · 5.19 KB

Architectural Blueprint: People & Tax Ecosystem

Vision

To build a modern, high-performance Java 21 monorepo that manages the lifecycle of various economic personas and provides a specialized, intelligent Tax Engine for calculating and optimizing Indian Income Tax.

1. High-Level Architecture

graph TD
    subgraph "Monorepo: java-migration-lab"
        Common["common-lib<br/>(Shared Models & Enums)"]
        
        PeopleApp["people-management-service<br/>(Port: 8080)"]
        TaxApp["tax-engine-service<br/>(Port: 8081)"]
        
        PeopleApp --> Common
        TaxApp --> Common
        
        TaxApp -- "Fetches Person Data" --> PeopleApp
        
        subgraph "Data Storage"
            DB[(PostgreSQL)]
            PeopleApp --> DB
            TaxApp --> DB
        end
    end
    
    ExternalSource["External Tax API / Scrapers"] -- "Future: Smart Suggestions" --> TaxApp
    User((User)) -- "REST API" --> PeopleApp
    User -- "Tax Queries" --> TaxApp
Loading

2. Component Breakdown

A. People Management Service

  • Purpose: The system of record for individuals.
  • Domain Model: Uses Java 21 Sealed Hierarchies to define personas:
    • Person (Sealed Interface)
      • Employee (Full-time & Contractors)
      • SelfEmployed (Freelancers, Doctors, Consultants)
      • BusinessOwner (LLCs, LLPs, Sole Proprietorships)
  • Tech Stack: Spring Boot 3.2+, Virtual Threads, JPA.

B. Tax Engine Service

  • Purpose: Specialized logic for Indian Taxation (Old vs New Regime).
  • Key Features:
    1. Tax Calculation: Pattern matching over the Person hierarchy to apply specific sections (Sec 192 for Employees, 44AD/44ADA for Business/Professionals).
    2. Deduction Engine: Handles 80C, 80D, HRA, and Standard Deductions.
    3. Smart Predictions: Suggestions for tax-saving investments based on income slabs.
  • Future: ML-based suggestions to maximize net take-home pay by analyzing external scraping results of latest schemes.

C. Common Library

  • Purpose: Shared DTOs, Enums (like TaxRegime, EmployeeType), and utility classes to ensure type safety across services.

3. Data Flow

  1. Registration: A User registers a Person via people-management-service.
  2. Assessment: The user requests a tax computation from tax-engine-service.
  3. Data Fetching: tax-engine-service calls people-management-service (via OpenFeign or WebClient) to get the latest income and profile details.
  4. Computation: The Tax Engine applies Java 21 switch expressions to determine the tax liability based on the latest Indian Budget slabs.
  5. Output: Returns a detailed breakdown of Tax, Cess, Surcharge, and Savings Tips.

3.1 Interaction Flow (Orchestration)

The following sequence explains how a tax calculation request is enriched with live person data.

sequenceDiagram
    participant User
    participant TaxApp as Tax Engine Service
    participant PeopleApp as People Service
    participant DB as PostgreSQL

    User->>TaxApp: GET /tax/calculate/{personId} (Regime: NEW)
    activate TaxApp
    
    Note right of TaxApp: Generated Correlation ID
    
    TaxApp->>PeopleApp: GET /people/{id}
    activate PeopleApp
    PeopleApp->>DB: Fetch Person Entity
    DB-->>PeopleApp: Person Data
    PeopleApp-->>TaxApp: Return Person (JSON Record)
    deactivate PeopleApp
    
    Note right of TaxApp: Orchestrator selects Strategy
    TaxApp->>TaxApp: Apply Deductions (Pattern Matching)
    TaxApp->>TaxApp: Calculate Tax & Cess
    
    TaxApp-->>User: Return TaxResult (Breakdown)
    deactivate TaxApp
Loading

3.2 Domain Model (Sealed Hierarchy)

The core Person model uses Java 21 advanced features to ensure type safety and exhaustive pattern matching.

classDiagram
    class Person {
        <<sealed interface>>
        +Long id
        +String name
        +String email
        +BigDecimal income()
    }

    class FullTimeEmployee {
        <<record>>
        +BigDecimal annualSalary
    }

    class Contractor {
        <<record>>
        +BigDecimal hourlyRate
        +int hoursWorked
    }

    class SelfEmployed {
        <<record>>
        +BigDecimal annualTurnover
        +String profession
    }

    class BusinessOwner {
        <<record>>
        +BigDecimal annualBusinessTurnover
        +String businessType
    }

    Person <|-- FullTimeEmployee
    Person <|-- Contractor
    Person <|-- SelfEmployed
    Person <|-- BusinessOwner
Loading

4. Java 21 Showcase Features

  • Pattern Matching for Switch: For complex multi-slab tax logic.
  • Record Patterns: To deconstruct income components instantly.
  • Structured Concurrency: To fetch person data and external investment rates in parallel.
  • Virtual Threads: To handle massive loads during tax filing seasons.

5. Roadmap

  • Phase 1: Restructure into Maven Multi-Module Monorepo.
  • Phase 2: Implement Person hierarchy in people-management-service.
  • Phase 3: Create tax-engine-service with basic Indian Tax Slabs (New Regime).
  • Phase 4: Add Deduction/Exemption modules (80C, HRA).
  • Phase 5: Intelligence layer - Scraping & Savings Suggestions.