Platform Architecture

Purpose

Developer documentation for the overall Autoconnecto platform architecture, including backend modules, frontend organization, telemetry flow, realtime behavior, and documentation generation.

System Overview

Autoconnecto uses a React and TypeScript frontend with a NestJS backend. The platform includes domain areas such as authentication, users, devices, device profiles, device attributes, telemetry, dashboards, alarms, assets, tenant features, MQTT ingest, MQTT acknowledgement flow, and generated documentation.

Backend Architecture

• NestJS modules organize the backend into domain-specific areas such as auth, users, devices, dashboards, telemetry, realtime, alarms, assets, and tenant functionality.
• Controllers expose HTTP endpoints.
• DTOs define request and response contracts.
• Services contain orchestration and business logic.
• Realtime and telemetry paths support live updates and historical querying.
• Documentation generation is hosted in the backend and writes generated markdown output.

Frontend Architecture

• The frontend is organized into feature folders that group UI by platform domain.
• Shared API modules coordinate calls into backend endpoints and contracts.
• Stores and hooks provide shared state, telemetry access, and runtime data resolution.
• Dashboard runtime behavior composes widgets, selected context, state selection, and telemetry-aware rendering.

Major Platform Domains

• Auth — authentication, guards, onboarding, and identity flow.
• Users — user administration and access-related flows.
• Devices — device lifecycle, state, and operational management.
• Device Profiles — reusable configuration and rule definitions.
• Device Attributes — persisted and runtime device metadata.
• Telemetry — historical and current telemetry query flow.
• Dashboards — layout, widgets, runtime views, and stateful rendering.
• Realtime — live update delivery and UI synchronization.
• Alarms — alarm lifecycle, acknowledgement, and investigation.
• Assets — asset grouping and device association.
• Tenant — tenant configuration and tenant attributes.
• MQTT — ingest and acknowledgement-related internal flows.

Data and Interaction Model

• Backend services expose structured APIs for frontend features and administrative flows.
• Frontend runtime behavior combines server responses, local UI state, and live telemetry updates.
• Dashboards and device views rely on both historical queries and live state updates.
• Multiple modules interact through shared identifiers such as tenant, device, asset, dashboard, and telemetry keys.

Documentation Architecture

• User docs are generated from behavior extractors and multi-page renderers.
• Swagger-based developer module docs are generated from Swagger/OpenAPI metadata.
• Dashboard-specific developer docs are generated from dashboard behavior extraction and dedicated developer renderers.
• Generated output is written under docs/generated/.
• Navigation metadata is written to docs/generated/navigation.json.

Change Detection and Automation

• Source hashes are used to avoid regenerating unchanged scopes.
• Automation scopes define which source roots and file extensions contribute to each documentation scope.
• Existing generation flow supports generating all scopes, changed scopes, and regeneration from changed files.
• Navigation is rebuilt after generation to keep the docs index synchronized with generated pages.

Developer Notes

• This document should act as the top-level technical entry point for understanding how backend domains, frontend domains, runtime data flow, and generated docs fit together.
• More specific implementation details should be continued in module-specific developer docs and dashboard-specific developer docs.