# subhankar-hub/professional-tax-portal architecture

> Architecture diagram of the GitHub repository subhankar-hub/professional-tax-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/subhankar-hub/professional-tax-portal
- Repository: https://github.com/subhankar-hub/professional-tax-portal

## Overview

##### Project Type & Purpose
- This is a full-stack, government-grade web application (“Professional Tax Portal”) that enables users to enroll, update, and view professional-tax details through an 8-step, OTP-protected wizard.
- The stack consists of:
- Frontend: React (TypeScript) with Vite, Tailwind CSS, Radix UI/shadcn/ui
- Backend A: Spring Boot (Java 17+) exposing RESTful APIs
- Backend B: Node.js/Express serverless functions (in the `api/` folder), deployed to Vercel or similar
- Database: PostgreSQL (with automated schema + master-data initialization)
- External Service: Fast2SMS for OTP delivery

##### File Structure Highlights
- Root:
- `api/` – serverless endpoints (health, master-data, OTP)
- `backend-professional-tax-portal/` – Spring Boot application (MVC layers, DTOs, repos, services, controllers, SQL scripts)
- `frontend-professional-tax-portal/` – Vite/React app (pages, components, hooks, API client, shared schema)
- DB setup & helper scripts (`setup_postgres.sh`, `new_db_schema.sql`, etc.)
- Deployment configurations (`docker-compose`, Vercel config, Maven wrapper, etc.)

##### Architectural Patterns & Design Principles
- Frontend/Backend separation: SPA communicating over HTTP to API layers
- MVC in Spring Boot: controllers → services → repositories → database
- Serverless micro-APIs (`api/`) for edge-deployed functions (low-latency around OTP and master-data queries)
- Database initialization service to auto-seed master tables on startup
- 8-step wizard UI with state management (React hooks + TanStack Query)

a. Main Components
- Web Client (React SPA)
- Serverless API Layer (Node/Express in `api/`)
- Monolith Backend (Spring Boot app)
- PostgreSQL Database
- External SMS Gateway (Fast2SMS)
- DevOps/Deployment (Docker, Vercel, CI/CD pipeline)
b. Relationships & Data Flow
1. User interacts with React wizard →
2. React uses `lib/api.ts` to call either Serverless functions (for master-data & OTP) or Spring Boot endpoints (for enrollment CRUD) →
3. Serverless functions or Spring Boot controllers validate input →
4. Spring Boot services persist or query Postgres (via JPA repos) →
5. OTPService in Spring Boot calls Fast2SMS API → back to user →
6. Admin endpoints in Spring Boot manage DB initialization/reset →
7. DevOps deploys frontend to Vercel, backend + DB in Docker containers or cloud.
c. Core Patterns
- Layered architecture in Spring Boot (Config, Controller, Service, Repository, Entity)
- Micro-edge functions for high-volume or low-latency endpoints
- Client-side state + query caching (React Query)
- Infrastructure as code (shell scripts, Docker Compose, Vercel config)
d. Key Technologies
- React/TypeScript, Vite, Tailwind CSS, shadcn/ui
- Spring Boot, Maven, Java 17, ModelMapper, CORS config
- Node.js, Express, Vercel serverless
- PostgreSQL, schema.sql, data.sql
- Fast2SMS API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer" 
        direction TB
        ReactSPA["React SPA"]:::frontend
        EntryPoint["main.tsx"]:::frontend
        Pages["Pages (Enrollment & Routing)"]:::frontend
        EnrollmentComponents["Enrollment Components"]:::frontend
        UILibrary["UI Library Components"]:::frontend
        Hooks["React Hooks & State Management"]:::frontend
        APIClient["API Client (lib/api.ts)"]:::frontend
        QueryClient["Query Client Config"]:::frontend
        SharedSchema["Shared TypeScript Schemas"]:::frontend
    end

    %% Serverless Layer
    subgraph "Serverless API Layer" 
        direction TB
        ServerlessAPI["Serverless API (Node/Express)"]:::serverless
        Health["Health Check Endpoint"]:::serverless
        MasterData["Master-Data Endpoints"]:::serverless
        OTP["OTP Endpoints"]:::serverless
    end

    %% Monolith Backend
    subgraph "Monolith Backend" 
        direction TB
        SpringApp["Spring Boot App"]:::monolith
        Bootstrapper["Application Bootstrapper"]:::monolith
        Controllers["MVC Controllers"]:::monolith
        Services["Service Layer"]:::monolith
        Repositories["Repository Layer"]:::monolith
        Entities["Domain Entities"]:::monolith
        DTOs["Data Transfer Objects"]:::monolith
        Configs["Configuration Classes"]:::monolith
        DBInit["DB Schema & Seed Scripts"]:::monolith
    end

    %% Database
    Postgres[(PostgreSQL Database)]:::database

    %% External Service
    Fast2SMS(("Fast2SMS Service")):::external

    %% DevOps Deployments
    subgraph "Deployment Environments"
        direction TB
        Vercel["Vercel (SPA & Serverless)"]:::devops
        DockerCloud["Docker/Cloud (Spring Boot & Postgres)"]:::devops
    end

    %% User Interaction
    User["User"]:::external

    %% Connections
    User -->|"Interacts with Wizard"| ReactSPA
    ReactSPA -->|"GET/POST master-data & OTP"| ServerlessAPI
    ReactSPA -->|"POST /api/enrollment & admin|health"| SpringApp

    ServerlessAPI --> Health
    ServerlessAPI --> MasterData
    ServerlessAPI --> OTP

    SpringApp --> Controllers
    Controllers --> Services
    Services --> Repositories
    Repositories --> Postgres
    Services -->|Uses| DBInit
    Services -->|OTPService calls| Fast2SMS
    Fast2SMS -.->|Response| Services

    DevOpsDeployFront["Deploy"]:::devops --> Vercel
    DevOpsDeployBack["Deploy"]:::devops --> DockerCloud
    Vercel --> ReactSPA
    Vercel --> ServerlessAPI
    DockerCloud --> SpringApp
    DockerCloud --> Postgres

    %% Click Events - Frontend
    click ReactSPA "https://github.com/subhankar-hub/professional-tax-portal/tree/main/frontend-professional-tax-portal/client"
    click EntryPoint "https://github.com/subhankar-hub/professional-tax-portal/blob/main/frontend-professional-tax-portal/client/src/main.tsx"
    click Pages "https://github.com/subhankar-hub/professional-tax-portal/tree/main/frontend-professional-tax-portal/client/src/pages"
    click EnrollmentComponents "https://github.com/subhankar-hub/professional-tax-portal/tree/main/frontend-professional-tax-portal/client/src/components/enrollment"
    click UILibrary "https://github.com/subhankar-hub/professional-tax-portal/tree/main/frontend-professional-tax-portal/client/src/components/ui"
    click Hooks "https://github.com/subhankar-hub/professional-tax-portal/tree/main/frontend-professional-tax-portal/client/src/hooks"
    click APIClient "https://github.com/subhankar-hub/professional-tax-portal/blob/main/frontend-professional-tax-portal/client/src/lib/api.ts"
    click QueryClient "https://github.com/subhankar-hub/professional-tax-portal/blob/main/frontend-professional-tax-portal/client/src/lib/queryClient.ts"
    click SharedSchema "https://github.com/subhankar-hub/professional-tax-portal/blob/main/frontend-professional-tax-portal/shared/schema.ts"

    %% Click Events - Serverless
    click ServerlessAPI "https://github.com/subhankar-hub/professional-tax-portal/tree/main/api/"
    click Health "https://github.com/subhankar-hub/professional-tax-portal/blob/main/api/health.js"
    click MasterData "https://github.com/subhankar-hub/professional-tax-portal/blob/main/api/master-data/areas.js"
    click OTP "https://github.com/subhankar-hub/professional-tax-portal/blob/main/api/otp/send.js"

    %% Click Events - Monolith
    click SpringApp "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/"
    click Bootstrapper "https://github.com/subhankar-hub/professional-tax-portal/blob/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/ProfessionaltaxportalApplication.java"
    click Controllers "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/controller"
    click Services "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/service"
    click Repositories "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/repository"
    click Entities "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/entity"
    click DTOs "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/dto"
    click Configs "https://github.com/subhankar-hub/professional-tax-portal/tree/main/backend-professional-tax-portal/src/main/java/io/example/professionaltaxportal/config"
    click DBInit "https://github.com/subhankar-hub/professional-tax-portal/blob/main/backend-professional-tax-portal/src/main/resources/schema.sql"

    %% Styles
    classDef frontend fill:#C3DDF9,stroke:#0366d6,color:#000
    classDef serverless fill:#D2F8D2,stroke:#28a745,color:#000
    classDef monolith fill:#FFE5B4,stroke:#e67e22,color:#000
    classDef database fill:#F2E6FF,stroke:#8e44ad,color:#000
    classDef external fill:#E8E8E8,stroke:#7f8c8d,color:#000
    classDef devops fill:#FDEBD0,stroke:#f39c12,color:#000
```
