# Property Valuation Portal - Architecture Overview
## System Architecture Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ Desktop Browser │ │ Mobile Browser (PWA) │ │
│ │ - Chrome, Firefox, │ │ - Android, iOS │ │
│ │ Safari, Edge │ │ - Offline Support │ │
│ │ - React SPA │ │ - Service Worker │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
│ │ │ │
│ └──────────────────────────────────────┘ │
│ │ │
│ │ HTTPS │
└──────────────────────────────┼──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ CDN / CLOUDFLARE LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ - Static Assets Delivery (JS, CSS, Images) │
│ - SSL/TLS Termination │
│ - DDoS Protection │
│ - Caching │
└──────────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ - Rate Limiting │
│ - JWT Token Validation │
│ - Request Logging │
│ - Load Balancing │
└──────────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Fastify Backend (Node.js) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Auth │ │ Valuation │ │ Document │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Photo │ │ Workflow │ │ Report │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ User │ │ Admin │ │ Notification│ │ │
│ │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │ │
└───────────────────────────────┼─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ PostgreSQL 18+ DB │ │ Object Storage │ │
│ │ + PostGIS Extension │ │ (S3-compatible) │ │
│ │ │ │ │ │
│ │ - Valuations │ │ - Documents (PDF, DOC) │ │
│ │ - Properties │ │ - Photos (JPG, PNG) │ │
│ │ - Users & Roles │ │ - Generated Reports │ │
│ │ - Workflow States │ │ │ │
│ │ - Audit Logs │ │ Signed URLs │ │
│ │ - GeoSpatial Data │ │ CDN Delivery │ │
│ │ (Boundaries, Points) │ │ │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL INTEGRATIONS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Google Maps │ │ Email/SMS │ │ Bank APIs │ │
│ │ API │ │ Gateway │ │ (Future) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## Component Architecture
### Frontend Architecture (React SPA)
```
src/
├── components/ # Reusable UI components
│ ├── common/ # Common components (Button, Input, Card)
│ ├── layout/ # Layout components (Header, Sidebar, Footer)
│ ├── forms/ # Form components (ValuationForm, etc.)
│ ├── maps/ # Map components (MapView, BoundaryDrawer)
│ └── charts/ # Chart components (Dashboard charts)
│
├── pages/ # Page components (one per screen)
│ ├── Dashboard/
│ ├── Valuations/
│ │ ├── ValuationList.tsx
│ │ ├── CreateValuation.tsx
│ │ ├── BasicInformation.tsx
│ │ ├── PropertyDetails.tsx
│ │ ├── SiteMap.tsx
│ │ └── ValuationCalculation.tsx
│ ├── Documents/
│ ├── Photos/
│ ├── Review/
│ ├── Approval/
│ ├── Reports/
│ └── Admin/
│
├── hooks/ # Custom React hooks
│ ├── useAuth.ts
│ ├── useValuation.ts
│ ├── useWorkflow.ts
│ └── useMap.ts
│
├── services/ # API service layer
│ ├── api.ts # Base API client (Axios/Fetch)
│ ├── authService.ts
│ ├── valuationService.ts
│ ├── documentService.ts
│ ├── photoService.ts
│ └── adminService.ts
│
├── stores/ # State management (Context API or Zustand)
│ ├── authStore.ts
│ ├── valuationStore.ts
│ └── uiStore.ts
│
├── types/ # TypeScript type definitions
│ ├── valuation.types.ts
│ ├── user.types.ts
│ ├── workflow.types.ts
│ └── api.types.ts
│
├── utils/ # Utility functions
│ ├── validators.ts # Form validation functions
│ ├── formatters.ts # Data formatters
│ ├── calculations.ts # Valuation calculations
│ └── helpers.ts # Helper functions
│
├── constants/ # Constants and enums
│ ├── workflow.constants.ts
│ ├── validation.constants.ts
│ └── routes.constants.ts
│
└── App.tsx # Main app component
```
---
### Backend Architecture (Fastify)
```
src/
├── modules/ # Feature modules
│ ├── auth/
│ │ ├── auth.controller.ts
│ │ ├── auth.service.ts
│ │ ├── auth.routes.ts
│ │ └── auth.schema.ts # Zod validation schemas
│ │
│ ├── valuations/
│ │ ├── valuations.controller.ts
│ │ ├── valuations.service.ts
│ │ ├── valuations.routes.ts
│ │ └── valuations.schema.ts
│ │
│ ├── documents/
│ ├── photos/
│ ├── workflow/
│ ├── reports/
│ ├── users/
│ └── admin/
│
├── database/ # Database layer
│ ├── client.ts # Database client (Prisma/Drizzle)
│ ├── migrations/ # Database migrations
│ ├── seeds/ # Seed data
│ └── schema/ # Database schema definitions
│
├── middleware/ # Middleware functions
│ ├── auth.middleware.ts # JWT validation
│ ├── rbac.middleware.ts # Role-based access control
│ ├── logging.middleware.ts # Request logging
│ └── error.middleware.ts # Error handling
│
├── services/ # Shared services
│ ├── storage.service.ts # File storage (S3)
│ ├── email.service.ts # Email notifications
│ ├── sms.service.ts # SMS notifications
│ └── maps.service.ts # Google Maps integration
│
├── utils/ # Utility functions
│ ├── validators.ts
│ ├── calculations.ts
│ ├── formatters.ts
│ └── helpers.ts
│
├── types/ # TypeScript type definitions
│ └── index.ts
│
├── config/ # Configuration
│ ├── database.config.ts
│ ├── storage.config.ts
│ └── env.config.ts
│
└── index.ts # Application entry point
```
---
## Database Schema Overview
### Core Tables
```
┌────────────────────────────────────────────────────────────────────┐
│ VALUATIONS (Main entity) │
├────────────────────────────────────────────────────────────────────┤
│ id (UUID, PK) │
│ valuation_number (Text, Unique, Indexed) │
│ bank_id (FK → banks) │
│ property_type (Enum: plot/independent_house/apartment) │
│ status (Enum: draft/survey/submitted/review/approval/approved) │
│ priority (Enum: high/medium/low) │
│ created_by (FK → users) │
│ assigned_surveyor (FK → users) │
│ assigned_keyin (FK → users) │
│ assigned_reviewer (FK → users) │
│ assigned_approver (FK → users) │
│ created_at (Timestamp) │
│ updated_at (Timestamp) │
│ submitted_at (Timestamp) │
│ approved_at (Timestamp) │
│ ... (workflow timestamps) │
└────────────────────────────────────────────────────────────────────┘
│
├─── 1:1 ───┐
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ PROPERTIES │ │ APPLICANTS │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ valuation_id (FK) │ │ valuation_id (FK) │
│ address │ │ applicant_name │
│ state_id (FK) │ │ co_applicant_name │
│ district_id (FK) │ │ owner_name │
│ mandal_id (FK) │ │ contact_mobile │
│ village_id (FK) │ │ contact_email │
│ pincode │ │ representative_name │
│ latitude │ │ ... │
│ longitude │ └──────────────────────┘
│ survey_number │
│ plot_number │
│ house_number │
│ ... (location data) │
└──────────────────────┘
│
├─── 1:1 ───┐
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ PROPERTY_DETAILS │ │ BOUNDARIES │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ property_id (FK) │ │ property_id (FK) │
│ shape_of_site │ │ boundary_polygon │
│ level │ │ (PostGIS Geometry)│
│ development_status │ │ boundary_geojson │
│ infrastructure │ │ (JSON) │
│ locality_class │ │ north_as_per_doc │
│ locality_type │ │ south_as_per_doc │
│ ... │ │ east_as_per_doc │
│ (site characteristics) │ west_as_per_doc │
└──────────────────────┘ │ north_actual │
│ south_actual │
│ east_actual │
│ west_actual │
│ ... │
└──────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ VALUATION_DATA │
├────────────────────────────────────────────────────────────────────┤
│ id (UUID, PK) │
│ valuation_id (FK → valuations) │
│ valuation_method (Enum: land_and_building/composite) │
│ land_unit (Enum: acres_guntas/acres_cents/sqmtrs/sqyds/sqft) │
│ land_area_document (Decimal) │
│ land_area_plan (Decimal) │
│ land_area_actual (Decimal) │
│ land_area_adopted (Decimal) │
│ road_effected_area (Decimal) │
│ nala_effected_area (Decimal) │
│ splay_area (Decimal) │
│ buffer_area (Decimal) │
│ net_land_area (Decimal) │
│ land_rate_type (Enum: guideline/market) │
│ land_rate (Decimal) │
│ land_value (Decimal) -- calculated │
│ building_area_plan (Decimal) │
│ building_area_actual (Decimal) │
│ building_area_adopted (Decimal) │
│ building_rate (Decimal) │
│ building_age (Integer) │
│ depreciation_percentage (Decimal) │
│ building_value (Decimal) -- calculated │
│ total_property_value (Decimal) -- calculated │
│ distress_sale_value (Decimal) -- calculated │
│ forced_sale_value (Decimal) -- calculated │
│ realizable_value (Decimal) -- calculated │
│ created_at (Timestamp) │
│ updated_at (Timestamp) │
└────────────────────────────────────────────────────────────────────┘
```
### Supporting Tables
```
┌──────────────────────┐ ┌──────────────────────┐
│ DOCUMENTS │ │ PHOTOS │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ valuation_id (FK) │ │ valuation_id (FK) │
│ document_type_id(FK)│ │ category │
│ document_name │ │ caption │
│ file_name │ │ file_name │
│ file_path (S3 URL) │ │ file_path (S3 URL) │
│ file_size │ │ thumbnail_path │
│ version_number │ │ latitude │
│ parent_document_id │ │ longitude │
│ uploaded_by (FK) │ │ gps_accuracy │
│ uploaded_at │ │ exif_data (JSON) │
│ status │ │ annotations (JSON) │
│ ... │ │ uploaded_by (FK) │
└──────────────────────┘ │ uploaded_at │
└──────────────────────┘
┌──────────────────────┐ ┌──────────────────────┐
│ COMMENTS │ │ ACTIVITY_LOGS │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ valuation_id (FK) │ │ valuation_id (FK) │
│ parent_comment_id │ │ user_id (FK) │
│ comment_text │ │ action_type │
│ comment_type │ │ action_description │
│ created_by (FK) │ │ entity_type │
│ created_at │ │ entity_id │
│ ... │ │ old_value (JSON) │
└──────────────────────┘ │ new_value (JSON) │
│ ip_address │
│ user_agent │
│ created_at │
└──────────────────────┘
```
### Reference Tables
```
┌──────────────────────┐ ┌──────────────────────┐
│ BANKS │ │ USERS │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ bank_name │ │ employee_id (Unique)│
│ bank_code (Unique) │ │ email (Unique) │
│ logo_url │ │ password_hash │
│ sla_days │ │ first_name │
│ multi_level_approval│ │ last_name │
│ contact_person │ │ mobile │
│ email │ │ primary_role_id(FK) │
│ status │ │ team_id (FK) │
│ ... │ │ status │
└──────────────────────┘ │ last_login_at │
│ ... │
┌──────────────────────┐ └──────────────────────┘
│ BANK_CONFIGS │ │
├──────────────────────┤ │ M:M
│ id (UUID, PK) │ ▼
│ bank_id (FK) │ ┌──────────────────────┐
│ config_type │ │ USER_ROLES │
│ config_data (JSON) │ ├──────────────────────┤
│ ... │ │ user_id (FK) │
└──────────────────────┘ │ role_id (FK) │
└──────────────────────┘
┌──────────────────────┐ │
│ LOCATIONS │ ▼
├──────────────────────┤ ┌──────────────────────┐
│ id (UUID, PK) │ │ ROLES │
│ location_type │ ├──────────────────────┤
│ parent_id (FK) │ │ id (UUID, PK) │
│ location_name │ │ role_name │
│ location_code │ │ role_description │
│ status │ │ permissions (JSON) │
│ ... │ │ ... │
└──────────────────────┘ └──────────────────────┘
┌──────────────────────┐ ┌──────────────────────┐
│ RATES │ │ LOOKUP_VALUES │
├──────────────────────┤ ├──────────────────────┤
│ id (UUID, PK) │ │ id (UUID, PK) │
│ location_id (FK) │ │ category │
│ rate_type │ │ value │
│ rate_per_unit │ │ display_order │
│ unit │ │ parent_id (FK) │
│ effective_from │ │ status │
│ effective_to │ │ ... │
│ ... │ └──────────────────────┘
└──────────────────────┘
```
---
## API Endpoints Overview
### Authentication
```
POST /api/v1/auth/login # User login
POST /api/v1/auth/logout # User logout
POST /api/v1/auth/refresh # Refresh JWT token
POST /api/v1/auth/forgot-password # Forgot password
POST /api/v1/auth/reset-password # Reset password
GET /api/v1/auth/me # Get current user info
```
### Valuations
```
GET /api/v1/valuations # List valuations (filtered)
POST /api/v1/valuations # Create new valuation
GET /api/v1/valuations/:id # Get valuation details
PUT /api/v1/valuations/:id # Update valuation
DELETE /api/v1/valuations/:id # Delete valuation (soft)
POST /api/v1/valuations/:id/submit # Submit for next stage
POST /api/v1/valuations/:id/clone # Clone valuation
GET /api/v1/valuations/:id/history # Get change history
GET /api/v1/valuations/my-queue # Get user's work queue
```
### Property Details
```
GET /api/v1/valuations/:id/property # Get property details
PUT /api/v1/valuations/:id/property # Update property details
GET /api/v1/valuations/:id/boundaries # Get boundary data
PUT /api/v1/valuations/:id/boundaries # Update boundary data
POST /api/v1/valuations/:id/calculate # Calculate valuation
```
### Documents
```
GET /api/v1/valuations/:id/documents # List documents
POST /api/v1/valuations/:id/documents # Upload document
GET /api/v1/documents/:docId # Get document details
GET /api/v1/documents/:docId/download # Download document
PUT /api/v1/documents/:docId # Update document metadata
DELETE /api/v1/documents/:docId # Delete document
GET /api/v1/documents/:docId/versions # Get version history
```
### Photos
```
GET /api/v1/valuations/:id/photos # List photos
POST /api/v1/valuations/:id/photos # Upload photo
GET /api/v1/photos/:photoId # Get photo details
PUT /api/v1/photos/:photoId # Update photo metadata
DELETE /api/v1/photos/:photoId # Delete photo
PUT /api/v1/photos/:photoId/annotations # Save annotations
```
### Workflow
```
GET /api/v1/workflow/stages # Get workflow stages
POST /api/v1/valuations/:id/review # Submit review
POST /api/v1/valuations/:id/approve # Approve valuation
POST /api/v1/valuations/:id/reject # Reject valuation
POST /api/v1/valuations/:id/query # Raise query
POST /api/v1/valuations/:id/reassign # Reassign valuation
GET /api/v1/workflow/pending-reviews # Get pending reviews
GET /api/v1/workflow/pending-approvals # Get pending approvals
```
### Reports
```
GET /api/v1/reports/dashboard # Get dashboard data
POST /api/v1/reports/generate # Generate custom report
GET /api/v1/reports/templates # List report templates
GET /api/v1/reports/saved # List saved reports
POST /api/v1/reports/export # Export report (PDF/Excel)
```
### Users & Admin
```
GET /api/v1/users # List users
POST /api/v1/users # Create user
GET /api/v1/users/:id # Get user details
PUT /api/v1/users/:id # Update user
DELETE /api/v1/users/:id # Deactivate user
GET /api/v1/roles # List roles
GET /api/v1/roles/:id/permissions # Get role permissions
PUT /api/v1/roles/:id/permissions # Update permissions
```
### Reference Data
```
GET /api/v1/banks # List banks
GET /api/v1/locations # List locations (hierarchical)
GET /api/v1/rates # List rates
GET /api/v1/lookups/:category # Get lookup values
GET /api/v1/config/system # Get system config
PUT /api/v1/config/system # Update system config
```
---
## Security Architecture
### Authentication Flow
```
1. User Login
├─ POST /api/v1/auth/login {email, password}
├─ Backend validates credentials
├─ Generate JWT token (access + refresh)
└─ Return tokens + user info
2. Authenticated Request
├─ Client adds JWT token in Authorization header
├─ API Gateway validates token
├─ Decode token → Extract user ID + role
├─ RBAC middleware checks permissions
└─ Allow/Deny request
3. Token Refresh
├─ Access token expires (30 min)
├─ Client uses refresh token
├─ POST /api/v1/auth/refresh {refresh_token}
└─ Backend issues new access token
4. Two-Factor Authentication (Optional)
├─ After login, require 2FA code
├─ Send OTP via SMS/Email/Authenticator
├─ Validate OTP
└─ Issue final JWT tokens
```
### Role-Based Access Control (RBAC)
```
Permission Check:
├─ Extract user role from JWT token
├─ Check route permissions from roles table
├─ Check resource ownership (if applicable)
│ Example: Can user edit this valuation?
│ ├─ Is user Creator AND status = Draft? ✓ Allow
│ ├─ Is user Surveyor AND status = Survey? ✓ Allow
│ └─ Otherwise? ✗ Deny
└─ Return 403 Forbidden if unauthorized
```
---
## Deployment Architecture
### Production Deployment
```
┌─────────────────────────────────────────────────────────────┐
│ CLOUDFLARE / DNS │
│ - Domain: valuations.jr-solutions.com │
│ - SSL/TLS Certificate │
│ - CDN for static assets │
└────────────────────┬────────────────────────────────────────┘
│
┌────────┴────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Frontend Server │ │ API Server │
│ (Cloudflare │ │ (Cloud VM/ │
│ Pages) │ │ Container) │
│ │ │ │
│ - React SPA │ │ - Fastify │
│ - Static Assets │ │ - Node.js 20+ │
│ - Service Worker│ │ - PM2 Process │
│ │ │ Manager │
└──────────────────┘ └────────┬─────────┘
│
┌──────────┴──────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ PostgreSQL DB │ │ Object Storage │
│ + PostGIS │ │ (S3/R2) │
│ │ │ │
│ - Primary DB │ │ - Documents │
│ - Replica (RO) │ │ - Photos │
└─────────────────┘ └─────────────────┘
```
### Development Environment
```
Local Machine:
├─ Frontend: npm run dev (Vite dev server on :5173)
├─ Backend: npm run dev (Fastify on :3000)
├─ Database: PostgreSQL Docker container on :5432
└─ Storage: MinIO Docker container on :9000 (S3-compatible)
```
---
## Performance Optimization Strategies
### Frontend
- **Code Splitting**: Lazy load routes and components
- **Tree Shaking**: Remove unused code
- **Image Optimization**: WebP format, lazy loading, responsive images
- **Caching**: Service Worker for offline support, Cache API
- **Bundle Size**: < 500 KB gzipped for initial load
- **Virtual Scrolling**: For large lists (1000+ items)
- **Debounced Search**: 300ms delay to reduce API calls
### Backend
- **Database Indexing**: Index frequently queried columns
- **Query Optimization**: Use EXPLAIN ANALYZE, avoid N+1 queries
- **Caching Layer**: Redis for session/lookup data (future)
- **Connection Pooling**: Reuse database connections
- **Pagination**: Limit query results to 25-100 items
- **Async Operations**: Background jobs for heavy tasks (report generation)
### Database
- **PostGIS Spatial Indexing**: GIST indexes on geometry columns
- **Partial Indexes**: Index only active records
- **Materialized Views**: For complex report queries
- **Table Partitioning**: Partition by date (if data grows large)
---
## Scalability Considerations
### Horizontal Scaling
- **API Servers**: Load balance across multiple instances
- **Database**: Read replicas for read-heavy operations
- **File Storage**: Object storage auto-scales
### Vertical Scaling
- **Database**: Increase CPU/RAM as data grows
- **API Server**: Increase resources per instance
### Caching Strategy (Future)
- **Redis**: Session storage, lookup data, frequently accessed data
- **CDN**: Static assets, photos, documents
---
**END OF ARCHITECTURE OVERVIEW**