Skip to main content

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.