Backend API

The Xylem backend is a NestJS 10 application that serves as the central API for the platform. It handles authentication, project management, file processing, AI integration, and regulatory analysis.

Project Structure

xylem-backend/
├── src/
│   ├── main.ts                  # Application bootstrap
│   ├── app.module.ts            # Root module (imports all feature modules)
│   ├── auth/                    # Authentication & authorization
│   ├── users/                   # User CRUD
│   ├── organizations/           # Organization management
│   ├── roles/                   # Role & permission management
│   ├── projects/                # Project CRUD & sharing
│   ├── project-variant/         # Project variant management
│   ├── survey-maps/             # DWG/DXF file processing
│   ├── catalog/                 # Floorplan unit catalog
│   ├── regulatory/              # Regulatory rules engine
│   ├── gemini/                  # Google Gemini AI integration
│   ├── openai/                  # OpenAI integration
│   ├── prisma/                  # Prisma service provider
│   ├── config/                  # App configuration
│   ├── shared/                  # Shared utilities
│   └── admin/                   # Admin-specific endpoints
├── prisma/
│   ├── schema.prisma            # Database schema
│   ├── migrations/              # Migration history
│   └── seed.ts                  # Database seeder
├── assets/                      # Static GIS data files
├── scripts/                     # Python helper scripts
├── templates/                   # Email templates (Handlebars)
├── uploads/                     # User file uploads directory
└── static/                      # Served static files

Module Overview

Module	Primary Endpoints	Description
Auth	/auth/*	Login, register, refresh tokens, email verification, password reset
Users	/users/*	User profile CRUD, avatar upload
Organizations	/organizations/*	Org CRUD, invitations, join requests
Roles	/roles/*	Role management, permission assignment
Projects	/projects/*	Project CRUD, sharing, cover images
Project Variant	/project-variants/*	Variant CRUD, product mix, solutions
Survey Maps	/survey-maps/*	DWG upload, conversion pipeline
Catalog	/catalog/*	Floorplan unit management, DXF parsing
Regulatory	/regulatory/*	Rules CRUD, variable registry, evaluation
Gemini	Internal service	AI metadata extraction from PDFs
Admin	/admin/*	Admin-only operations

Environment Variables

Variable	Required	Description
PORT	No	Server port (default: 4000)
DATABASE_URL	Yes	PostgreSQL connection string
SHADOW_DATABASE_URL	No	Prisma shadow database for migrations
UPLOAD_PATH	Yes	Directory for file uploads
JWT_SECRET	Yes	JWT signing secret
JWT_EXPIRATION_TIME	Yes	JWT token expiration duration
JWT_REFRESH_SECRET	Yes	JWT refresh token secret
JWT_VERIFICATION_SECRET	Yes	JWT email verification secret
GEMINI_API_KEY	Yes	Google Gemini API key
GOOGLE_GEOCODE_API_KEY	Yes	Google Maps Geocoding API key
OPENAI_API_KEY	No	OpenAI API key
MAIL_USER	Yes	Email sender address
MAIL_CLIENT_ID	Yes	OAuth2 client ID for email
MAIL_CLIENT_SECRET	Yes	OAuth2 client secret for email
MAIL_REFRESH_TOKEN	Yes	OAuth2 refresh token for email
MAIL_FROM	Yes	From address for outgoing emails

External Dependencies

System Packages

These must be installed at the OS level:

Tool	Package	Purpose
ODAFileConverter	ODA	Primary DWG → DXF conversion
dwgread	LibreDWG	Fallback DWG converter
xvfb-run	xvfb	Virtual framebuffer for headless ODA
ogr2ogr	GDAL	DXF → GeoJSON conversion
gdalwarp	GDAL	GeoTIFF raster clipping
gdal2xyz.py	GDAL	Pixel data extraction
python3	python3	Floorplan processing script

External APIs

API	Purpose	Env Variable
Google Gemini	AI metadata extraction from survey PDFs	GEMINI_API_KEY
Google Geocoding	Address → lat/lon coordinates	GOOGLE_GEOCODE_API_KEY
Open-Meteo Elevation	Ground elevation lookup (free)	—
SME Converter	DXF → PDF conversion	—

Static Asset Files

These must be present in the assets/ directory:

File	Purpose
CCZM_BANGALORE_WGS84.tif	AAI Color-Zone Map GeoTIFF for elevation zone analysis
authorities.geojson	Authority boundary polygons (BDA, BBMP, etc.)
blr_roadWidth.geojson	Bangalore road network with width data

Development

# Install dependencies
npm install

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Start development server (hot reload)
npm run start:dev

# Build for production
npm run build

# Run tests
npm test