System Architecture

Xylem follows a service-oriented architecture with six independent services communicating over HTTP. All services run on a single AWS EC2 instance, managed by PM2, and fronted by Nginx with SSL via Let's Encrypt.

Service Map

Service	Repository	Language	Framework	Port	Domain
Backend API	xylem-backend	TypeScript	NestJS 10	4000	api.xylem.city
Frontend	xylem-frontend	TypeScript	Next.js 15	4801	xylem.city
Admin Panel	xylem-admin	JavaScript	React + Vite	Static	admin.xylem.city
Geo Server	xylem-geo	TypeScript	Express	4830	geo.xylem.city
Simulation	xylem-simulation-backend	Python	FastAPI	4902	—
SME Analyzer	xylem-sme-analyzer	Python	FastAPI	4802	sme.xylem.city

Technology Stack

Backend (Node.js)

• Runtime: Node.js v24.14.0
• Package Manager: npm 11.9.0
• API Framework: NestJS 10 with Passport JWT authentication
• ORM: Prisma 5 with PostgreSQL
• Validation: Zod + nestjs-zod
• Email: Nodemailer with OAuth2 (Gmail)
• AI: Google Gemini SDK, OpenAI SDK
• Geo Libraries: Turf.js, GDAL (ogr2ogr, gdalwarp), LibreDWG

Frontend

• Framework: Next.js 15 with Turbopack, React 19
• Mapping: Mapbox GL JS, react-map-gl
• 3D: Three.js
• Icons: Lucide React
• CAD Viewer: dxf-viewer
• Solar: SunCalc

Admin Panel

• Bundler: Vite 7
• UI: React 19, Lucide React
• Routing: React Router DOM 7
• Visual Programming: ReactFlow 11 (regulatory rules)
• Math: math.js (rule evaluation)

Python Services

• Runtime: Python ≥ 3.13
• Package Manager: uv
• API Framework: FastAPI + Uvicorn
• Geometry: Shapely, GeoJSON
• Solar Analysis: pvlib, pandas, matplotlib
• CAD: ezdxf
• PDF Rendering: CairoSVG

Data Flow

User uploads DWG ──► Backend (NestJS)
                        │
                        ├── DWG → DXF  (ODAFileConverter / LibreDWG)
                        ├── DXF → GeoJSON  (ogr2ogr)
                        ├── AI Metadata Extraction  (Gemini)
                        ├── Geocoding  (Google Maps API)
                        └── Zone Analysis  (GDAL + GeoTIFF)
                              │
                              ▼
                     Site stored in DB (Prisma)
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
     Regulatory Engine    Simulation         Frontend
     (graph-based rules)  (tower optimizer)  (Mapbox 3D map)
            │                 │                 │
            ▼                 ▼                 ▼
     Compliance Report   Solutions JSON    Interactive 3D
                          (scored/ranked)   Visualization

Inter-Service Communication

From	To	Protocol	Purpose
Frontend → Backend	REST/HTTPS	All data CRUD, auth, file uploads
Backend → Simulation	HTTP (internal)	Tower optimization, floorplate generation
Backend → SME Analyzer	HTTP (internal)	DXF to PDF conversion
Backend → Google Gemini	HTTPS	Survey map AI metadata extraction
Backend → Google Geocoding	HTTPS	Address → coordinates
Frontend → Geo Server	HTTPS	Map tile requests (raster + vector)
Admin → Backend	REST/HTTPS	Layer, user, org, rule management
Admin → Geo Server	REST/HTTPS	Layer CRUD operations