Module Boundaries
Purpose
Section titled “Purpose”This document defines initial module boundaries for V1.
The platform should start with a small number of deployables and strong internal module boundaries. A premature microservice architecture is not desired.
Deployables
Section titled “Deployables”web-console
Section titled “web-console”Owns:
- User interface.
- UI routing.
- UI state.
- Calls to platform API.
Does not own:
- Authorization decisions.
- Data filtering.
- Tenant isolation.
- Business rules.
- Direct database access.
platform-api
Section titled “platform-api”Owns:
- Public HTTP API.
- Authentication integration.
- Authorization checks.
- Tenant and organization management.
- User and role management.
- Device registry.
- Device type registry.
- Telemetry query API.
- Export API.
- Audit logging.
Does not own:
- MQTT connection handling.
- Direct long-running telemetry ingestion.
- Decoder execution for live ingestion, except administrative validation or test runs.
- Frontend rendering.
mqtt-ingestion-worker
Section titled “mqtt-ingestion-worker”Owns:
- MQTT connection to Network Server.
- MQTT subscription handling.
- Minimal envelope validation.
- Publishing raw ingestion events to internal broker.
Does not own:
- Device authorization.
- Decoder execution.
- Long-term telemetry storage.
- UI/API behavior.
telemetry-worker
Section titled “telemetry-worker”Owns:
- Processing raw ingestion events.
- Device lookup.
- Raw payload storage.
- Decoder execution.
- Normalized measurement storage.
- Ingestion failure handling.
- Dead-letter behavior.
Does not own:
- Public HTTP APIs.
- User management.
- UI behavior.
- Network Server device synchronization.
Shared Packages
Section titled “Shared Packages”packages/contracts
Section titled “packages/contracts”May contain:
- TypeScript contract types.
- API schemas.
- Event schemas.
- Decoder input/output types.
Must not contain:
- Database clients.
- Runtime service implementations.
- Business logic with side effects.
- Environment-specific configuration.
packages/config
Section titled “packages/config”May contain:
- Configuration parsing.
- Configuration validation.
- Shared config helpers.
Must not contain:
- Secrets.
- Environment-specific hard-coded values.
packages/database
Section titled “packages/database”May contain:
- Database connection helpers.
- Migration helpers.
- Shared database types.
- Repository base utilities.
Must not contain:
- Feature business logic that belongs to a module.
packages/logging
Section titled “packages/logging”May contain:
- Logger setup.
- Correlation ID helpers.
- Safe log formatting.
Must not contain:
- Module-specific business logic.
packages/operability
Section titled “packages/operability”May contain:
- Health endpoint helpers.
- Readiness endpoint helpers.
- Metrics registry and exposition helpers.
- Shared operation endpoint conventions.
Must not contain:
- Module-specific business logic.
- Database, MQTT, NATS, decoder, authentication, or authorization behavior.
- Tenant-owned data access.
packages/telemetry-decoder-sdk
Section titled “packages/telemetry-decoder-sdk”May contain:
- Decoder interfaces.
- Decoder helper functions.
- Measurement output types.
- Decoder test utilities.
Must not contain:
- Database access.
- Network access.
- Filesystem access.
- Secret access.
Extraction Principle
Section titled “Extraction Principle”Modules may later be extracted into separate services if justified by scaling, security, deployment, or operational needs.
Until then, use clear module boundaries without unnecessary service fragmentation.