Application Gateway — The Custom Server¶
One Server to Bridge Them All¶
We built a custom Application Gateway that serves as the single entry point for all web-based interactions with the WinCC OA platform. Running on port 3000, it bridges 6 different backend services, serves all visual editors and viewers, and provides a unified, modern web layer on top of the entire ecosystem.
Why We Built This
Managing 6 different backend services on different ports, each with its own API conventions and error formats, would create significant complexity for every frontend tool. The gateway centralizes everything behind a single origin — one URL, one authentication layer, one error format — making the entire web ecosystem simple to develop and maintain.
What It Serves¶
Visual Editors & Viewers¶
Every web-based tool is served from this single server:
| URL | Tool |
|---|---|
/graph-editor.html |
Menu Editor (node-based canvas) |
/plant-graph-editor.html |
Plant Composition Editor |
/tables-graph-editor.html |
SQL Pipeline Editor |
/manual-viewer.html |
Documentation Viewer |
/manual-admin.html |
Documentation Admin Dashboard |
/diary-viewer.html |
Operator Diary Timeline |
/paraWeb.html |
Datapoint Manager |
One server, one port, all tools. No separate installations, no complex URL routing, no CORS issues between services.
Smart Proxy Architecture¶
Multi-Backend Orchestration¶
The gateway routes requests to 6 different backend services, each on its own port:
| Backend | Port | Role |
|---|---|---|
| WinCC OA REST API | 8080 | Menus, datapoints, panels, icons, PARA, plants |
| Aggregation Engine | 8081 | Time-series data aggregation |
| Derived Tables Engine | 8082 | Computed table generation |
| Manual Engine | 8083 | Documentation generation |
| PDF Service | 3001 | PDF export |
| PostgreSQL | 5432 | Direct database access |
Each backend failure is handled gracefully — if a service is down, the gateway returns a clear error message instead of crashing. The frontend never needs to know which port a service runs on or how to handle each backend's quirks — the gateway abstracts all of this away.
Direct PostgreSQL Access¶
We built a complete set of database endpoints that bypass WinCC OA entirely when direct SQL access is more efficient:
- Query execution with automatic LIMIT (prevents runaway queries)
- Schema introspection — table listing with column types and estimated row counts
- Column type grouping — automatic categorization into numeric, text, temporal, boolean
- SQL injection prevention — parameterized queries throughout, table name validation against
information_schema - Test data generator — creates a realistic production database (10 lines, 120 orders, 500 measurements, 40 operators) for demos and development
Workflow Execution Engine¶
We implemented a multi-step workflow orchestrator directly in the gateway:
- Topological sorting (Kahn's algorithm) resolves execution order from dependency declarations
- Circular dependency detection with clear error reporting
- Parameter passing between steps — results from step N substitute into step N+1 via
$param_<stepId>_<column>syntax - Transactional execution — each step in its own database transaction with rollback on failure
This powers the Tables Editor's pipeline execution — complex multi-table queries run as coordinated workflows.
AI Integration¶
The gateway includes an endpoint to invoke Claude directly from the server:
- Subprocess spawning with stdin piping (avoids shell argument length limits)
- 180-second timeout for long-running analysis
- Environment variable cleaning to prevent nested session conflicts
- Token count estimation for cost tracking
This enables the Manual Engine to generate documentation without any external API service — everything runs locally.
Performance & Caching¶
| Resource | Cache Strategy | TTL |
|---|---|---|
| Static assets (HTML, JS, CSS) | ETag + HTTP cache | 1 hour |
| WinCC OA icons | ETag + HTTP cache | 1 hour |
| Manual screenshots | ETag + HTTP cache | 10 minutes |
| Diary screenshots | ETag + HTTP cache | 10 minutes |
| All responses | gzip compression | Always on |
The gzip middleware alone reduces bandwidth by ~70% — critical when serving large node editor canvases over the network.
Health Monitoring¶
A simple health endpoint reports server status, uptime, and WinCC OA API availability:
GET /health → { status: 'ok', timestamp: '...', winccoa_api: 'reachable' }
Why This Architecture Wins¶
The Gateway Pattern
By centralizing all web traffic through a single server, we achieved:
- Zero CORS issues — everything is same-origin
- Unified authentication — one point of control
- Simple deployment — one
node server.jsserves the entire web ecosystem - Compression everywhere — all responses gzipped automatically
- Consistent error handling — one error format across all backends
- Graceful degradation — individual backend failures don't crash the system