Dependency Policy

Purpose

Dependencies must support self-hosted operation, commercial use, and future customer-owned on-premise Kubernetes deployments.

This policy applies to runtime dependencies, development dependencies, build tooling, generated artifacts, and optional integrations.

Dependency Classes

Runtime dependencies are packaged with applications or required for production operation. They need explicit review for:

license compatibility with commercial use and redistribution,
self-hosted and on-premise operation,
required external services,
operational ownership,
security update path,
replacement strategy when the dependency is adapter-facing.

Development dependencies are used for local checks, CI, tests, documentation, or build tooling. They still need license review, but they must not become required runtime services.

Optional proprietary integrations must be isolated behind adapters and must not be required for core platform operation.

License Expectations

Allowed by default after review:

MIT,
Apache-2.0,
BSD-2-Clause,
BSD-3-Clause,
ISC.

Requires explicit review before adoption:

LGPL,
MPL,
EPL,
AGPL,
GPL,
custom or source-available licenses,
licenses with field-of-use, SaaS, hosting, telemetry, or redistribution restrictions.

Unknown license metadata blocks adoption until clarified.

Change Requirements

When adding dependencies, the same change must document:

package name and purpose,
runtime or development classification,
license,
whether the dependency requires a proprietary service,
whether it affects deployment, Helm values, secrets, or environment variables,
whether it changes a public or cross-module contract.

Runtime dependencies that affect contracts, configuration, deployment, security, tenancy, persistence, or operations also require matching documentation and tests.

Phase 2 Tooling Dependencies

Phase 2 adds these root development dependencies:

Package	Purpose	License	Runtime impact
`eslint`	JavaScript and TypeScript linting	MIT	None
`@eslint/js`	ESLint recommended JavaScript rules	MIT	None
`typescript-eslint`	ESLint support for TypeScript	MIT	None
`eslint-config-prettier`	Disable conflicting formatting rules	MIT	None
`prettier`	Repository formatting baseline	MIT	None
`prettier-plugin-astro`	Format Astro files when present	MIT	None
`vitest`	Unit test runner	MIT	None
`globals`	Shared ESLint global definitions	MIT	None
`@types/node`	Node.js type declarations	MIT	None

These dependencies are dev-only, do not add production services, do not require secrets, and do not change application behavior.

Phase 3 Local Infrastructure Images

Phase 3 adds Docker images for local infrastructure only. They are required for local development of the V1 architecture, but they do not add application code, public contracts, Helm values, production secrets, or tenant data paths.

Image	Purpose	License review	Runtime impact
`timescale/timescaledb:2.28.1-pg17-oss`	Local PostgreSQL/TimescaleDB database	TimescaleDB Apache 2 Edition: Apache-2.0	Local infrastructure only
`nats:2.14.2-alpine`	Local NATS server with JetStream enabled	NATS server: Apache-2.0	Local infrastructure only
`eclipse-mosquitto:2.1.2-alpine`	Local mock MQTT broker	EPL-2.0 or EDL-1.0 / BSD-3-Clause	Local infrastructure only

The TimescaleDB image uses the -oss tag so the local default stays on the Apache-2.0 edition. If later phases require TimescaleDB Community features, that must be reviewed and documented as a separate licensing decision.

The Apache-2.0 edition is sufficient for the Phase 3 local database container and for validating connectivity. It does not close the later database decision for automated TimescaleDB retention policies, compression, continuous aggregates, or other features that may require the Timescale License.

The Mosquitto image is accepted for the local mock broker because it is isolated to local development, does not become a required production service, and can be replaced by another MQTT broker behind the same MQTT protocol boundary.

Phase 4 Runtime Dependencies

Phase 4 adds runtime dependencies for the shared service baseline. They do not require proprietary services and are compatible with self-hosted and future customer-owned Kubernetes deployments.

Package	Purpose	License	Runtime impact
`zod`	Runtime configuration schema validation	MIT	Application library, no external service
`pino`	Structured JSON logging	MIT	Application library, no external service
`fastify`	Health, readiness, and metrics HTTP endpoints	MIT	Application library, no external service
`prom-client`	Prometheus-compatible metrics exposition	Apache-2.0	Application library, no external service

These dependencies affect runtime behavior, configuration validation, logs, metrics, and operation endpoints. They do not add new Helm values yet, do not introduce secrets, do not add persistence, and do not change tenant-owned data paths.

Phase 4.5 Deployment Images and Tooling

Phase 4.5 adds container packaging, a Helm chart, and GitOps deployment infrastructure for the dedicated Kubernetes test and controlled production environments.

Application container images use node:24-bookworm-slim as the runtime and build base. The image packages the service and its production dependencies only. It must not contain local environment files, SSH keys, Kubernetes credentials, or production secrets.

The Helm chart under infra/helm/sens-platform can deploy embedded infrastructure for the early single-node environments:

Image	Purpose	License review	Runtime impact
`timescale/timescaledb:2.28.1-pg17-oss`	PostgreSQL/TimescaleDB StatefulSet	TimescaleDB Apache 2 Edition: Apache-2.0	Early single-node environments
`nats:2.14.2-alpine`	NATS JetStream StatefulSet	NATS server: Apache-2.0	Early single-node environments
`eclipse-mosquitto:2.1.2-alpine`	Test mock MQTT StatefulSet	EPL-2.0 or EDL-1.0 / BSD-3-Clause	Test environment only
Argo CD	GitOps sync and environment status overview	Apache-2.0	Cluster operations component
cert-manager	ACME certificate management	Apache-2.0	Cluster operations component
Traefik	Existing k3s ingress controller	MIT	Existing cluster ingress component

The chart references Kubernetes Secrets by name and must not render secret values from committed defaults. The dedicated environments use sens-test-timescaledb-auth or sens-production-timescaledb-auth for the embedded TimescaleDB password and ghcr-pull for GHCR image pulls.

CI uses Helm only for rendering and linting. Helm is a deployment validation tool and does not add an application runtime dependency.