Architecture
CONTEXUS combines a marketing and admin surface (this Next.js site) with Open IoT Hub services for ingestion, storage, and visualization. See Open IoT Hub for the product story; this page focuses on how components interact in deployment.
Runtime topology
In a typical Docker Compose deployment:
- Web container — Next.js 16 App Router in standalone mode, served on host port
9001 - PostgreSQL — relational metadata, users, CMS content, meeting bookings, and IoT entity model; exposed on host
5433 - Attached assets volume — uploaded images and dashboard exports persisted across redeploys
[Field devices] -- BACnet / Modbus / MQTT / LoRaWAN / OPC-UA -->
[Protocol adapters] --> [Ingestion API] --> [PostgreSQL + TS store]
|
v
[Dashboards / Rules / Admin UI]Protocol layer
Each protocol runs as a bounded adapter with its own connection pool and retry policy. Adapters normalise readings into a canonical point model (site → device → point) so dashboards and APIs do not depend on wire format. Deep dives:
Application layers
Presentation (Next.js)
Server components render marketing pages, documentation, and authenticated admin routes under /at_admin. Client components handle interactive dashboards, booking flows, and ticket submission.
API surface
Route handlers in app/api/ implement REST endpoints for admin CRUD, health checks, meetings, and IoT operations. Legacy Express routes remain in server/routes.ts for backward compatibility when not running pure Next standalone.
Data access
Drizzle ORM schema lives in shared/schema.ts. Both app/lib/db.ts and server/db.ts detect Neon serverless vs standard PostgreSQL from DATABASE_URL.
Security boundaries
- Session cookies for admin and integrator consoles; HTTPS termination at the reverse proxy
- Protocol credentials stored encrypted or in vault integrations (deployment-specific)
- Multi-tenant row-level scoping — see multi-tenancy
Extensibility
Six featured modules are open source on GitHub; optional modules are governed by licensing. Integrators can white-label the UI, swap auth providers, and add custom widgets through the dashboard builder binding model.
Observability
Use docker-compose logs for container stdout, /api/health for synthetic checks, and application metrics exporters where enabled. Common failures are catalogued in troubleshooting.
Next steps
Explore a running stack, review the open source repositories, estimate ROI for a deployment, or talk with the CONTEXUS team about integration and licensing.
Module licensing details are summarised on /licensing. Browse reference dashboards in the gallery.