diff --git a/distributed-systems-final-report.tex b/distributed-systems-final-report.tex index bd6a74f..ba2af3e 100644 --- a/distributed-systems-final-report.tex +++ b/distributed-systems-final-report.tex @@ -7,597 +7,558 @@ \usepackage{cleveref} % this must be the last package to be loaded \usepackage{comment} \usepackage{xcolor} +\usepackage{microtype} \newcommand{\emailaddr}[1]{\href{mailto:#1}{\texttt{#1}}} +\newcommand{\quotes}[1]{``#1''} \newenvironment{guideline}[1][gray]{\color{#1}}{} +\newcommand{\coreTestCount}{220} +\newcommand{\coverageThreshold}{60} + \title{\LARGE - Factory Manager Report +Factory Manager Report } \subtitle{Final Report for the Distributed Systems Course 2025/2026} -% Consider watching: -% https://www.youtube.com/watch?v=ihxSUsJB_14 -% https://www.youtube.com/watch?v=XTFWaV55uDo - \author{ David Cohen \\ \emailaddr{david.cohen@studio.unibo.it} \and Giulia Nardicchia \\ \emailaddr{giulia.nardicchia@studio.unibo.it} - \and } \date{\today} \begin{document} -\maketitle - -\begin{abstract} - Up to $\sim$2000 characters briefly describing the project. -\end{abstract} - -\section*{Disclaimer (if needed)} - -During the preparation of this work, the author(s) used [NAME TOOL / SERVICE] to [REASON]. - -After using this tool/service, -the author(s) reviewed and edited the content as needed -and take(s) full responsibility for the content of the final report/artifact. - -\section*{Quick \LaTeX{} suggestions} - -If you need to cite a reference, you can use the \texttt{cite} command, -like providing the BibTex key of some entry in the \texttt{references.bib} file, -e.g.: \cite{adams1995hitchhiker}. - -You can find pre-coocked BibTex entries for most Computer Science papers on \href{https://dblp.uni-trier.de/}{DBLP}. - -If you need to include an image, -let \LaTeX{} decide where to put it by using the \texttt{figure} environment, -with a \texttt{includegraphics} command inside it. -% -If your need to reference a figure, -use the \texttt{label} command to assign a label to the figure, -and then use the \texttt{cref} command to reference it. -% -Put figures in the \texttt{figures} folder. -% -A complete example is shown in \cref{fig:universe}. - -\begin{figure} - \centering - \includegraphics[width=0.5\textwidth]{figures/universe.jpg} - \caption{This is an example image} - \label{fig:universe} -\end{figure} - -Do \textbf{not} put any placement constraint on figures, -such as \texttt{[h]} or \texttt{[h!]}. -% -Same considerations apply for other floating elements -(e.g. tables, algorithms, listings, etc.). - -Do \textbf{not} use the \texttt{\textbackslash\textbackslash} or \texttt{\textbackslash newline} commands to break lines. - -Just leave an empty line between two paragraphs to start a new one. -% -The new line will be automatically indented. -% -This is intended: it is the \LaTeX{} way to separate capoverses. - -\section{Concept}\label{concept} - -\begin{guideline} -Here you should explain: - -\begin{itemize} - \item The type of product developed with that project, for example (non-exhaustive): - % - \begin{itemize} - \item Application (with GUI, be it mobile, web, or desktop) - \item Command-line application (CLI could be used by humans or scripts) - \item Library - \item Web-service(s) - \end{itemize} - - \item Use case description: - % - \begin{itemize} - \item \emph{what} is the software doing? - \item \emph{where} are the users? - \item \emph{when} and \emph{how frequently} do they interact with the system? - \item \emph{how} do they \emph{interact} with the system? which \emph{devices} are they using? - \item does the system need to \emph{store} user's \textbf{data}? \emph{which}? \emph{where}? - \item most likely, there will be \emph{multiple} \textbf{roles} - \end{itemize} - - \item Why is distribution needed? - % - \begin{itemize} - \item geographically distributed environments? - \item computation speedup? - \item resource sharing? - \item fault tolerance? - \item other reasons? - \end{itemize} - % - In any case, please elaborate. -\end{itemize} -\end{guideline} - -\section{Requirements Elicitation and Analysis}\label{requirements} - -\subsection{Functional Requirements}\label{functional-requirements} - - -\subsection{Non-Functional Requirements}\label{non-functional-requirements} - -\subsection{Implementation Requirements}\label{implementation-requirements} - -\begin{guideline} - \begin{itemize} - \item The requirements must explain \textbf{what} (not how) the software - being produced should do. - % + \maketitle + + \begin{abstract} + Factory Manager is a distributed system for monitoring industrial machinery inside a factory. + + The factory is organized in areas, and every area groups a set of machines. + + Each machine has sensors that measure power consumption, emissions, operating temperature, vibration and pressure. + + The system collects this telemetry, detects anomalies, and lets administrators and operators manage users, areas and machines through a REST API. + + The system is made of independent services: a set of Machine Simulators emulate real machines and publish sensor readings over MQTT, a Coordinator Service consumes these events, applies anomaly detection and updates the central state, and a Core REST Service exposes the HTTP API, takes care of authentication and authorization, and persists everything in MongoDB. + + An MQTT broker sits between the machines and the rest of the system, so they never talk to each other directly. + + Distribution comes directly from the domain: machines are physically spread across the factory, telemetry keeps arriving continuously from many sources at the same time, and the ingestion pipeline has to survive retries and duplicated events without corrupting the data. + + Services talk to each other through asynchronous publish/subscribe messaging (MQTT) and synchronous HTTP calls, and the whole infrastructure can be started locally with Docker Compose. + \end{abstract} + + \tableofcontents + + \section*{Disclaimer} + + During the preparation of this work, the author(s) used Large Language Models to speed up parts of the workflow: \begin{itemize} - \item you should not focus on the particular problems, but exclusively on - what you want the application to do. + \item resolving LaTeX compilation errors and warnings (for instance, diagnosing overfull \texttt{hbox} warnings and being advised to use the \texttt{sloppypar} environment as a fix); + \item used web tool \url{https://www.imagetomermaid.com/app} to convert raw diagram images into Mermaid source, so the diagrams could be edited more easily; + \item at the end, used ChatGPT to proofread the report and suggest improvements in grammar, spelling, and style. \end{itemize} - \item Requirements must be clearly identified, and possibly numbered + \section{Concept}\label{concept} - \item Requirements are divided into: - % - \begin{itemize} - \item \textbf{Functional}: some functionality the software should provide to the user + The product is a set of cooperating \textbf{web services} for industrial machinery monitoring. + + The main entry point for a human user is the HTTP API of the \textbf{Core REST Service}: it can be used directly (for example through its interactive documentation page) or, through a Web GUI built on top of it. + + The other two services, \textbf{Machine Simulator} and \textbf{Coordinator}, are headless processes: they just run in the background and nobody interacts with them directly. + + \subsection{Use case} - \item \textbf{Non-functional}: requirements that do not directly concern behavioural aspects, such as consistency, availability, etc. + The system targets a factory where machines are grouped into physical areas. - \item \textbf{Implementation}: constrain the entire phase of system realization, - for instance by requiring the use of a specific programming language and/or a specific software tool - % - \begin{itemize} - \item these constraints should be adequately justified by political / economic / administrative reasons\ldots{} - \item \ldots{} otherwise, implementation choices should emerge \emph{as a consequence of} design - \end{itemize} + Each machine keeps producing sensor readings (power consumption, emissions, operating temperature, vibration, pressure). + + The factory wants to store this telemetry, always know the current state of every machine (\emph{off}, \emph{operational} or \emph{anomaly}), and react when a sensor goes out of its normal range defined as \textbf{anomaly} behavior state. + + There are two human roles: + + \begin{itemize} + \item \textbf{Admin}: manages user accounts and has full access to every resource. + \item \textbf{Operator}: monitors machines, manages areas and machines, and reads telemetry, but cannot manage other users. \end{itemize} - \item If there are domain-specific terms, these should be explained in a glossary - - \item Each requirement must have its own \textbf{acceptance criterion} - % + Users work from the factory officesand interact with the system from desktop devices, mainly during working hours. + + Machines, on the other hand, talk to the system \textbf{all the time}: telemetry is published at a fixed interval (a few seconds), so the ingestion path receives a continuous, steady write load. + + The system stores user accounts (with hashed passwords and profile data), factory areas, machines with their current state and specifications, and the full history of telemetry events. + + All persistent data lives in MongoDB, owned by the Core REST Service. + + \subsection{Why distribution is needed} + + Distribution comes naturally from the domain itself: \begin{itemize} - \item these will be important for the validation phase + \item \textbf{Geographical distribution of the sources}: machines are physically spread across the factory and cannot host the central database or the business logic. They only publish small telemetry messages on the network. + \item \textbf{Decoupling and fault tolerance}: machines have to keep publishing even if the storage layer is temporarily down. The MQTT broker decouples producers from consumers, and the idempotent ingestion API makes retries safe. + \item \textbf{Scalability}: the number of machines can grow over time. Adding one only means adding a new publisher; the rest of the system does not change. + \item \textbf{Separation of concerns}: anomaly detection (by Coordinator) and data management (by Core REST Service) evolve independently, are developed separately , and even use different technologies (like TypeScript and JavaScript). \end{itemize} - \end{itemize} -\end{guideline} - \subsection{Relevant Distributed System Features}\label{ds-features} + \section{Requirements Elicitation and Analysis}\label{requirements} + + \subsection{Functional Requirements}\label{functional-requirements} + + \begin{description} + \item[FR1: Authentication.] A registered user can log in with email and password and obtain an access token. + + \emph{Acceptance criterion}: with valid credentials the API returns a signed JWT and the user profile; with wrong credentials, or for a deactivated user, it returns \texttt{401 Unauthorized}. + + \item[FR2: User management.] An admin can create, list, read, update and delete users, each with a role (\emph{admin} or \emph{operator}), contact data and preferences. + + \emph{Acceptance criterion}: CRUD operations succeed for an admin; user creation, update and deletion attempted by an operator return \texttt{403 Forbidden}; creating a user with an already used email returns \texttt{409 Conflict}; the password hash is never present in any API response. + + \item[FR3: Area management.] Authenticated users can create, list, read, update and delete factory areas (name and size). + + \emph{Acceptance criterion}: CRUD operations succeed for admins and operators; a duplicated area name returns \texttt{409 Conflict}. + + \item[FR4: Machine management.] Authenticated users can create, list, read, update and delete machines. A machine has a unique \texttt{serial}, a name, a reference to an existing area, sensor specifications and a state. + + \emph{Acceptance criterion}: creating a machine in a non-existing area returns \texttt{404 Not Found}; a duplicated \texttt{serial} returns \texttt{409 Conflict}; a new machine starts in the \emph{off} state. + + \item[FR5: Machine state lifecycle.] The state of a machine can only change along valid transitions: \emph{off} $\rightarrow$ \emph{operational}; \emph{operational} $\rightarrow$ \emph{off} or \emph{anomaly}; \emph{anomaly} $\rightarrow$ \emph{operational} or \emph{off}. + + \emph{Acceptance criterion}: a valid transition updates the machine; an invalid one (e.g. \emph{off} $\rightarrow$ \emph{anomaly}) returns \texttt{422 Unprocessable Entity}; a transition to \emph{anomaly} without the list of anomalous sensors returns \texttt{400 Bad Request}. + + \item[FR6: Telemetry ingestion.] The Coordinator can store telemetry events for existing machines. Each event carries a unique \texttt{eventId}, a sequence number, a timestamp, the five sensor readings and the anomaly evaluation. + + \emph{Acceptance criterion}: a valid event is stored and returned with \texttt{201 Created}; an event with an already stored \texttt{eventId} returns \texttt{409 Conflict}; an event for a non-existing machine returns \texttt{404 Not Found}. + + \item[FR7: Telemetry query.] Authenticated users can list telemetry filtered by machine and by time interval, with pagination and time ordering. + + \emph{Acceptance criterion}: the endpoint honours \texttt{machineId}, \texttt{from}, \texttt{to}, \texttt{limit}, \texttt{offset} and \texttt{sort} parameters, with safe defaults and a maximum page size. + + \item[FR8: Telemetry production.] Each simulated machine periodically publishes its sensor readings and a heartbeat message on the MQTT broker, on a topic that identifies the machine. + + \emph{Acceptance criterion}: with the stack running, telemetry and heartbeat messages appear on the broker at the configured interval. + + \item[FR9: Anomaly detection and forwarding.] The Coordinator consumes telemetry from the broker, evaluates it against the machine specifications, marks anomalous readings, and forwards telemetry and machine state updates to the Core REST Service. + + \emph{Acceptance criterion}: an out-of-range reading produces a telemetry record marked as anomaly and moves the machine to the \emph{anomaly} state. + \end{description} + + \subsection{Non-Functional Requirements}\label{non-functional-requirements} + + \begin{description} + \item[NFR1: Security of credentials.] Passwords are stored only as strong hashes (memory-hard algorithm); plain passwords never leave the login request. \emph{Acceptance}: the database contains no plain password and no API response contains a hash. + \item[NFR2: Access control.] Every data endpoint requires authentication, and write operations are restricted by role. \emph{Acceptance}: unauthenticated requests return \texttt{401}, unauthorized ones \texttt{403}. + \item[NFR3: Data integrity.] Uniqueness constraints (user email, machine \texttt{serial}, area name, telemetry \texttt{eventId}) are enforced at the database level, so they hold also under concurrent writes. \emph{Acceptance}: concurrent duplicated inserts produce exactly one document. + \item[NFR4: Idempotent ingestion.] Re-sending the same telemetry event must not create duplicates, so at-least-once delivery and retries are safe. \emph{Acceptance}: the second identical \texttt{POST} returns \texttt{409} and the history contains one record. + \item[NFR5: Interoperability.] The API is documented with a machine-readable contract (OpenAPI) so other components and future clients can integrate without reading the code. \emph{Acceptance}: the published specification validates and matches the implemented endpoints. + \item[NFR6: Maintainability.] Each service follows a layered architecture with automated tests, linting and CI on every change. \emph{Acceptance}: CI enforces lint, formatting, documentation validity and a minimum test coverage of \coverageThreshold\%. + \item[NFR7: Observability.] The services produce structured logs, and the Core REST Service exposes health and readiness endpoints. \emph{Acceptance}: \texttt{/api/health} always answers; \texttt{/api/ready} reflects the database connection. + \end{description} + + \subsection{Implementation Requirements}\label{implementation-requirements} + + \begin{description} + \item[IR1] The services run on Node.js (version 24 or newer) and are containerized with Docker; the whole infrastructure must start with Docker Compose\footnote{\url{https://docs.docker.com/compose/}}. This keeps the development environment identical for both team members and close to a production-like deployment. + \item[IR2] The Core REST Service is written in JavaScript (ES Modules) with Express and MongoDB; the Coordinator and the Machine Simulator are written in TypeScript. The choice reflects the background of the two authors and shows interoperability between heterogeneous components. + \item[IR3] Machine-to-system communication uses MQTT (Eclipse Mosquitto\footnote{\url{https://mosquitto.org/}} broker), a standard lightweight protocol for telemetry in industrial and IoT scenarios. + \item[IR4] Automated tests use the native Node.js test runner\footnote{\url{https://nodejs.org/api/test.html}} for the Core REST Service and Vitest for the TypeScript services; GitHub Actions\footnote{\url{https://docs.github.com/actions}} runs a separate CI workflow per service. + \end{description} + + \paragraph{Glossary.} + \emph{Area}: a physical zone of the factory that groups machines. + \emph{Machine}: a monitored industrial device with sensors and a lifecycle state. + \emph{Telemetry}: one set of sensor readings produced by a machine at a given time. + \emph{Anomaly}: a telemetry evaluation where at least one reading is outside the normal range declared in the machine specifications. + \emph{Heartbeat}: a periodic ``I am alive'' message published by a machine. + \emph{Coordinator}: the service that consumes machine events and updates the central state. + + \subsection{Relevant Distributed System Features}\label{ds-features} + + \begin{description} + \item[Transparency.] A user only sees one HTTP API, and does not need to know that telemetry travels through a broker and a separate Coordinator before reaching the database. Machines, on their side, only know an MQTT topic: they have no idea where the data ends up. Location transparency comes almost for free, since Docker resolves service names on the internal network. + + \item[Fault tolerance and dependability.] The broker keeps producers and consumers apart, so a temporary failure of the Coordinator or of the Core REST Service never stops the machines from publishing. Duplicate detection on \texttt{eventId} keeps the data consistent even under retries, and heartbeats make it possible to tell if a machine is still alive. Containers restart automatically (\texttt{restart: unless-stopped}), and the readiness endpoint tells the orchestrator when a service is ready to accept traffic. + + \item[Scalability.] The ingestion path is the part that really needs to scale: adding a machine just means adding one more MQTT publisher, which is cheap. + + \item[Security and trust.] The system stores personal data (names, emails, phone numbers) and credentials, so authentication (JWT), role-based authorization and password hashing are not optional extras but core requirements. Service-to-service calls use a separate pre-shared token, so the internal traffic between services never depends on a human account. + + \item[Resource sharing.] MongoDB and the broker are shared infrastructure used by every service. Coordination on shared data is left to the database itself, through unique indexes and atomic single-document updates. + + \item[Openness, interoperability, heterogeneity.] Every component talks over open protocols (HTTP/JSON, MQTT), and services are written in different languages (JavaScript and TypeScript) on purpose. The OpenAPI contract means any future client can consume the API without reading a line of the source code. + + \item[Evolvability and maintainability.] Each service has its own codebase, its own tests and its own CI pipeline, so it can be changed and redeployed on its own. Inside each service, a ports-and-adapters layering keeps the domain logic away from the frameworks. + + \item[Performance and concurrency.] Telemetry writes happen concurrently and never stop, but every single message is small, so the write throughput stays low regardless of the number of machines; the MongoDB index on \texttt{machineId} and \texttt{capturedAt} keeps time-range queries fast. Strict low-latency guarantees were never a goal of this project: it is a trade-off we accepted in exchange for a much simpler design. + + \item[Economy.] The whole system runs on one developer machine through Docker Compose, no paid infrastructure needed. + \end{description} + + \section{Design}\label{design} + + This chapter explains the strategies used to meet the requirements identified in the analysis. + + The design is technology-independent as much as possible; concrete technologies are discussed in \cref{implementation}. + + \subsection{Architecture}\label{architecture} + + The system follows a \textbf{microservices architectural style}, with three application services, each with one clear responsibility: - \begin{guideline} - Motivate which distributed system features are relevant for your project, and which are not. - % - \begin{itemize} - \item transparency \begin{itemize} - \item does your system need to hide distribution details from users or developers? - \item is it important that failures, location, or replication are invisible? + \item \textbf{Machine Simulator Service}: emulates a physical machine; it periodically generates sensor readings and publishes them, together with heartbeats, on the message broker. One instance runs per simulated machine. + \item \textbf{Coordinator Service}: the event-processing \quotes{brain} of the system; it consumes telemetry and heartbeat events, applies the anomaly-detection policies and pushes the results to the Core REST Service. + \item \textbf{Core REST Service}: the system of record; it exposes the HTTP API for users and internal services, enforces authentication and authorization, validates the machine state lifecycle and persists everything in the database. \end{itemize} - \item fault tolerance, dependability -- availability, reliability, integrity, maintainability, safety + We chose this style because the three responsibilities have very different shapes (a periodic producer, an event consumer, and a request/response server), different scaling needs, and were developed independently by the two of us. + + Putting everything into one monolithic application would have forced a single technology and a single deployment unit onto components that really have nothing in common except the domain. + + Inside each service we follow a lite \textbf{ports-and-adapters (hexagonal) architecture}, with a lightweight domain-driven design: a pure domain layer (entities, value objects, state machine, policies), an application layer with the use cases, and adapters for HTTP, persistence and messaging. + + In the Core REST Service the layering is: \texttt{domain} $\leftarrow$ \texttt{application} $\leftarrow$ \{\texttt{routes}, \texttt{persistence}, \texttt{security}\} $\leftarrow$ \texttt{bootstrap}, where \texttt{bootstrap} is the composition root that wires the concrete adapters into the use cases through dependency injection. + + \subsection{Infrastructure}\label{infrastructure} + + The infrastructure is composed of: + \begin{itemize} - \item what happens if a component fails? is uninterrupted service required? - \item is data loss or corruption unacceptable? - \item how quickly must the system recover from faults? + \item \textbf{MongoDB} (one instance): the only database of the system, owned by the Core REST Service. + \item \textbf{MQTT broker} (Eclipse Mosquitto, one instance): the asynchronous communication backbone between machines and the Coordinator. + \item \textbf{Core REST Service} (one instance, horizontally replicable): HTTP server on port 3000. + \item \textbf{Coordinator Service} (one instance): background consumer, no exposed port. + \item \textbf{Machine Simulator Service} ($N$ instances, one per machine): background publisher, no exposed port. + \item \textbf{Clients}: any HTTP client; currently the interactive API documentation page acts as the user interface, and a Web GUI is planned as future work. \end{itemize} - \item scalability + \Cref{fig:components} shows the components and how they communicate. + + \begin{figure} + \centering + \includegraphics[width=0.85\textwidth]{figures/components.pdf} + \caption{Components of the system and their communication channels.} + \label{fig:components} + \end{figure} + + In our reference deployment every component runs as a container on the same Docker network, on a single host. + + Nothing in the design requires this: the broker, the database and the services only talk to each other over the network, so they could just as well live on different hosts. + + Components find each other by \textbf{name}: Docker Compose resolves service names through its internal DNS (\texttt{mongo}, \texttt{mqtt-broker}), and every address is injected through environment variables (\texttt{MONGO\_URI}, \texttt{MQTT\_URL}). + + Nothing is hard-coded, so moving a component to a different host only means changing its environment. + + \subsection{Modelling}\label{modelling} + + The domain entities are: + \begin{itemize} - \item will the system need to handle increasing numbers of users, requests, or data? - \item is it expected to grow over time? + \item \textbf{User}: name, unique email, hashed password, role (\emph{admin} or \emph{operator}), active flag, last login time, phone number and UI preferences (theme, accessibility color filter). + \item \textbf{Area}: unique name and size; a logical container for machines. + \item \textbf{Machine}: unique \texttt{serial}, name, reference to its Area, sensor \emph{specifications} (measurement unit and normal range per sensor) and its \emph{machine state} (current state plus the list of anomalous sensors when in \emph{anomaly}). + \item \textbf{Telemetry}: an append-only event with unique \texttt{eventId}, machine reference, sequence number, capture timestamp, the five sensor readings and the anomaly evaluation. \end{itemize} - \item security, trust + The machine state is modeled as a small \textbf{finite state machine} in the domain layer with states \emph{off}, \emph{operational} and \emph{anomaly}, and an explicit table of valid transitions (see FR5), shown in \cref{fig:machine-states}. + + \begin{figure} + \centering + \includegraphics[width=0.55\textwidth]{figures/machine-states.pdf} + \caption{The machine lifecycle state machine.} + \label{fig:machine-states} + \end{figure} + + Modelling the state as part of the domain, and not inside the HTTP layer, guarantees that every writer, whether a human or a service, has to respect the same rules. + + Domain entities map to infrastructure quite directly: all four entities are persistent documents in MongoDB, owned exclusively by the Core REST Service. + + The Coordinator itself is stateless: it keeps no database of its own, and derives everything from the events it consumes plus the machine data it reads from the API. + + The Simulator only holds its own configuration (machine identity, publishing intervals, value ranges). + + The relevant domain events are: \emph{telemetry captured}, \emph{heartbeat emitted}, \emph{anomaly detected}, \emph{machine state changed}, \emph{user logged in}. + + Messages in the system fall into three kinds: \textbf{events} on the broker (telemetry, heartbeat), \textbf{commands} over HTTP (create/update/delete resources, update machine state, store telemetry) and \textbf{queries} over HTTP (list/read resources, telemetry history). + + So the state of the whole system is: users, areas, machines with their current state, and the full telemetry history, all sitting in the database, plus whatever messages are momentarily in flight on the broker. + + \subsection{Interaction}\label{interaction} + + Two interaction patterns live side by side in the system: + \begin{itemize} - \item is sensitive data being processed or stored? - \item are there multiple user roles with different permissions? - \item is authentication or authorization required? + \item \textbf{Publish/subscribe (asynchronous, event-based)} between machines and the Coordinator. Each simulator publishes on machine-specific topics (\texttt{factory/}\allowbreak\texttt{telemetry/}\allowbreak\texttt{\{machineId\}} and \texttt{factory/}\allowbreak\texttt{heartbeat/}\allowbreak\texttt{\{machineId\}}); the Coordinator subscribes with a wildcard (\texttt{factory/telemetry/+}), so producers and consumer do not know each other and do not need to be alive at the same time. + \item \textbf{Request/response (synchronous)} over HTTP for everything else: human clients call the Core REST Service, and the Coordinator calls the same API as an internal client. \end{itemize} - \item resource sharing + To make this concrete, here is the main end-to-end flow, shown in \cref{fig:telemetry-flow-ingestion,fig:telemetry-flow-state}: + + \begin{enumerate} + \item the Simulator generates a reading and publishes a telemetry event on its topic; + \item the broker delivers the event to the Coordinator; + \item the Coordinator validates and maps the message, evaluates the anomaly policies against the machine ranges, and produces an enriched telemetry event; + \item the Coordinator stores the event with \texttt{POST /api/telemetry} (authenticated with the service token); + \item if the anomaly evaluation changed the machine condition, the Coordinator updates the state with \texttt{PATCH /api/machines/\{id\}/state}; + \item users later read machines and telemetry through authenticated \texttt{GET} endpoints. + \end{enumerate} + + Storing telemetry and updating the machine state are kept as two separate operations on purpose: they are different responsibilities, with different validation rules, and only the second one has to respect the state machine. + + \begin{figure} + \centering + \includegraphics[width=\textwidth]{figures/telemetry-flow-ingestion.pdf} + \caption{Telemetry ingestion: from the machine to the stored event (steps 1--4).} + \label{fig:telemetry-flow-ingestion} + \end{figure} + + \begin{figure} + \centering + \includegraphics[width=\textwidth]{figures/telemetry-flow-state.pdf} + \caption{Machine state update and telemetry read (steps 5--6).} + \label{fig:telemetry-flow-state} + \end{figure} + + + \subsection{Behaviour}\label{behaviour} + + \textbf{Machine Simulator}: timer-driven and stateless. On every tick it generates a reading, inside or occasionally outside the configured ranges, and publishes it, without caring who is listening. + + \textbf{Coordinator}: event-driven and stateless. It reacts to every incoming message, routes it to the right processor (telemetry or heartbeat), applies its domain policies and turns the result into HTTP commands. Since it keeps no state of its own, it can be restarted at any moment with no recovery logic needed. + + \textbf{Core REST Service}: request-driven, and stateless between one request and the next. Every request gets authenticated, validated at the boundary, run through an application use case and persisted. All the system state lives in the database, which is exactly what makes the service safe to replicate. + + The Core REST Service is the only component allowed to change the system state, and it always does so under its own rules: the referenced areas and machines must exist, the transition must be allowed by the state machine, and an \emph{anomaly} state must always carry the list of anomalous sensors. + + Machine state changes are also logged as warnings (entering an anomaly, powering off) so this important behaviour stays observable. + + \subsection{Data and Consistency Issues}\label{data-and-consistency-issues} + + All persistent data (users, areas, machines, telemetry) is stored in MongoDB as \textbf{documents}. + + A document store fits this domain quite well: entities are self-contained aggregates with nested structures (sensor specifications, readings, preferences) that map naturally onto documents, telemetry is append-only, and the schema can evolve easily. + + Classical multi-document transactions are never needed, because every single write only touches one document. + + Only the Core REST Service ever queries the database. + + Writes come from users (resource management) and from the Coordinator (telemetry inserts and state updates); reads come from users and, at bootstrap time, from the Coordinator (list of machines). + + Telemetry inserts are the real concurrent-write hot spot, but since each one is an independent single-document insert, no locking is needed. + + There is no eventual consistency here to reason about: every write is a single document, so consistency is enforced exactly where it matters: + \begin{itemize} - \item do multiple users or components need access to shared resources? - \item is coordination or synchronization needed? + \item \textbf{unique indexes} on user email, machine \texttt{serial}, area name and telemetry \texttt{eventId} guarantee uniqueness at the database level, so it holds even under concurrency (the API turns the violation into \texttt{409 Conflict}); + \item \textbf{idempotency}: the unique \texttt{eventId} makes telemetry ingestion idempotent, which is exactly what makes at-least-once delivery upstream safe; + \item \textbf{single-document atomic updates} for machine state, so a state change is never applied only halfway; + \item a compound index on (\texttt{machineId}, \texttt{capturedAt}) keeps the time-range queries used by clients fast. \end{itemize} - \item openness, interoperability, heterogeneity of components + Components never share a database: data only moves between them through the API, so the Core REST Service stays the single authority on the stored state. + + \subsection{Fault-Tolerance}\label{fault-tolerance} + + There is currently no data replication: a single MongoDB instance holds the data, with a persistent Docker volume so it survives container restarts. + + Replication through a MongoDB replica set is a natural next step we foresee, and we discuss it in \cref{future-works}. + + Instead, the design puts its effort into \textbf{decoupling and safe retries}: + \begin{itemize} - \item Will your system interact with external systems or use components built with different technologies? - \item Is standardization or compatibility important? + \item \textbf{Heart-beating}: every machine publishes a periodic heartbeat on its own topic, and the Coordinator consumes it, so a \quotes{silent} machine can be detected. + \item \textbf{Retry safety}: if a call from the Coordinator to the Core REST Service fails or times out, the Coordinator can just retry it: duplicated telemetry gets rejected with \texttt{409} thanks to \texttt{eventId}, so a retry can never corrupt the history. + \item \textbf{Buffering}: if the Coordinator is down, machines simply keep publishing to the broker, which absorbs the backpressure; if the Core REST Service is down, the failure stays confined to the ingestion calls and does not spread anywhere else. + \item \textbf{Error handling}: the Core REST Service has one centralized error handler that turns domain errors and infrastructure errors (duplicate key, validation failure, malformed JSON) into HTTP responses with a stable shape (\texttt{code} + \texttt{message}), without ever leaking a stack trace. Anything unexpected becomes a \texttt{500} and gets logged. + \item \textbf{Process resilience}: containers restart automatically; the service shuts down gracefully on \texttt{SIGTERM} (it stops accepting new connections, then closes the database connection); \texttt{/api/ready} exposes the database connectivity so an orchestrator knows when it is safe to send traffic. \end{itemize} - \item evolvability, maintainability + \subsection{Availability}\label{availability} + + There is no caching layer in the system: users always read the freshest state of machines and telemetry, which is really the whole point of a monitoring system. + + HTTP caching is explicitly turned off (no \texttt{ETag}), so a client never gets a stale read on data that keeps changing. + + The reference deployment has no load balancer either, but since the Core REST Service is stateless and every instance is identical, scaling out just means running more replicas behind a normal HTTP load balancer. + + JWT authentication helps here too: any replica can verify a token on its own, without any shared session state. + + Under a network partition the system degrades gracefully instead of failing as a whole: machines keep publishing to the broker even if nobody is consuming; the Coordinator keeps consuming even if the API is unreachable, and can retry safely later; the API keeps serving reads and writes even if the broker side is down. + + The database stays the only real single point of failure for the API: should MongoDB eventually become unreachable, the readiness endpoint reports it, and the service answers with errors instead of risking corrupted data. This is the classic consistency/availability trade-off: on the write path, we chose consistency. + + \subsection{Security}\label{security} + + \textbf{Authentication} is required on every data endpoint of the Core REST Service, and comes in two forms: + \begin{itemize} - \item Will the system need to be updated or extended after deployment? - \item Is long-term maintenance a concern? + \item \textbf{Users} log in with email and password and get back a short-lived signed \textbf{JWT} (one hour by default), sent as a \texttt{Bearer} token on every following request. Logout is stateless: the client just discards the token. + \item \textbf{Internal services} (the Coordinator) authenticate with a pre-shared \textbf{service token}, sent in a dedicated header (\texttt{X-Service-Token}) and compared in constant time to avoid timing attacks. This way machine-to-machine traffic stays independent from human accounts. \end{itemize} - \item performance, concurrency, computation / communication efficiency, bandwidth + \textbf{Authorization} is role-based (RBAC), with two roles. + + Admins manage users; admins and operators manage areas and machines; telemetry ingestion is reserved to the service token, while reading telemetry requires a logged-in user. + + Reading a machine and updating its state accept either credential, since the Coordinator needs to do both as well. + + A deactivated user (\texttt{isActive = false}) simply cannot log in anymore, which gives admins an easy way to revoke access without deleting an account. + + \textbf{Cryptography}: passwords are hashed with \textbf{Argon2id}, a memory-hard function built to resist GPU brute force; JWTs are signed with a server-side secret (HMAC) and verified on every request. + + To add one more \quotes{safety net}, the password hash is excluded from database reads by default, and the API serializers work as \emph{whitelists}, so a new internal field can never leak out by accident. + + Every secret (JWT secret, service token, database URI) is passed through environment variables and never committed to the repository. + + \section{Implementation}\label{implementation} + + \textbf{Network protocols}: HTTP/1.1 for the API (request/response) and MQTT over TCP for machine events (publish/subscribe). + + \textbf{Data representation}: JSON everywhere, both in HTTP bodies and MQTT payloads, since it is native to the JavaScript/TypeScript stack and easy to read while debugging. + + \textbf{Database access}: MongoDB, queried through the Mongoose\footnote{\url{https://mongoosejs.com/}} ODM; schemas declare types, defaults, enums and indexes, and repositories wrap every query so the application layer never sees Mongoose. + + \textbf{Authentication}: JWT (HS256) through the \texttt{jsonwebtoken}\footnote{\url{https://www.npmjs.com/package/jsonwebtoken}} library for users; a pre-shared token compared with \texttt{crypto.timingSafeEqual} for services. + + \textbf{Authorization}: RBAC, implemented as a small \texttt{requireRole} middleware applied per route. + + \subsection{Technological details}\label{technological-details} + + \paragraph{Core REST Service (JavaScript).} + Built on Node.js 24 with native ES Modules, Express 5 and Mongoose 9. + + Express 5 forwards rejected promises to the error middleware on its own, so we did not need any async-handler wrapper: route handlers are plain \texttt{async} functions, and every failure ends up in one centralized error handler. + + Request validation uses Joi\footnote{\url{https://joi.dev/}} schemas, applied through three small factory middlewares (\texttt{validateBody}, \texttt{validateParams}, \texttt{validateQuery}); validation failures get converted into typed application errors (\texttt{AppError}) with stable error codes. + + Passwords are hashed with the \texttt{argon2}\footnote{\url{https://www.npmjs.com/package/argon2}} package (Argon2id). + + Logging goes through \texttt{pino}\footnote{\url{https://github.com/pinojs/pino}}, with per-request logging handled by \texttt{pino-http}. + + The API is described by an OpenAPI 3 document, served through Swagger UI\footnote{\url{https://swagger.io/tools/swagger-ui/}} at \texttt{/api/docs}; the specification itself is validated with \texttt{swagger-parser}, both locally and in CI. + + The codebase sticks to the hexagonal layering quite strictly: the domain layer has zero external dependencies; use cases are factory functions that receive their dependencies as arguments (\texttt{createUserService(\{ userRepository, passwordHasher \})}); routers are factories too, and the \texttt{bootstrap} folder is the only place where the concrete adapters get wired together. + + This made unit testing almost effortless: every dependency can simply be swapped for a plain object. + + \paragraph{Coordinator and Machine Simulator (TypeScript).} + Both services are written in TypeScript (strict mode) and run with \texttt{tsx}; they use the \texttt{mqtt} client library, \texttt{pino} for logging and Vitest for testing. + + The Coordinator models sensors as value objects with ranges, and anomaly detection as a set of pluggable policies evaluated by an \texttt{AnomalyDetector} domain service. + + \section{Validation}\label{validation} + + \subsection{Automatic Testing}\label{automatic-testing} + + The Core REST Service is tested with the \textbf{native Node.js test runner} (\texttt{node:test} + \texttt{node:assert/strict}), with no mocking library at all: test doubles are just plain objects implementing only the methods a test needs. + + At the time of writing the suite counts \textbf{\coreTestCount{} passing tests}, organized by layer: + \begin{itemize} - \item Are there strict requirements on response time or throughput? - \item Will many operations happen in parallel? - \item Is network usage a concern? + \item \textbf{Application-layer unit tests}: every use case (users, auth, areas, machines, telemetry) is tested against in-memory fake repositories and hashers. These tests cover the business rules of FR1--FR7: role defaults, duplicate handling, the state-machine transitions, the anomaly-details rule, pagination normalization and the serializer whitelists (no \texttt{passwordHash} in any output, ever). + \item \textbf{Domain and shared-kernel unit tests}: the machine state transition table and the \texttt{AppError} factories. + \item \textbf{Middleware and security unit tests}: JWT authentication, service-token authentication (including the missing or misconfigured token cases), role checking, request validation, the centralized error handler mappings and the 404 handler. + \item \textbf{Model tests}: Mongoose schema rules are checked with \texttt{validateSync()}, with no database connection at all, which keeps the suite fast and self-contained. + \item \textbf{Route tests (light integration)}: every router is mounted on a \emph{real} HTTP server listening on a random port, with fake services injected. For each endpoint they cover the happy path, one validation rejection, the authentication/authorization rejections and the not-found case: the HTTP contract, without duplicating what is already tested at the service level. \end{itemize} - \item economy, costs + The whole suite runs in a couple of seconds with \texttt{npm test} (a single test file can be run with \texttt{node --test }). + + CI (GitHub Actions, one workflow per service, triggered only on the paths of that service) runs lint, format check, \textbf{OpenAPI validation} and the test suite with a \textbf{\coverageThreshold\% coverage threshold} on lines, functions and branches, using the native Node.js coverage. + + Since the OpenAPI document gets validated in the very same pipeline as the code, the published contract cannot drift away from what is actually implemented. + + \subsection{Acceptance test}\label{acceptance-test} + + We also ran a few punctual manual tests on the running stack (Docker Compose): + + \begin{sloppypar} + \begin{itemize} + \item the full user journey through Swagger UI: seed the first admin (\texttt{npm run seed:admin}), log in, create an operator, create an area, create a machine, drive its state through valid and invalid transitions, insert telemetry with the service token and read it back with filters; + \item failure behaviour: stopping MongoDB and checking that \texttt{/api/ready} turns \texttt{503} and the API returns errors without ever crashing; restarting the containers and checking that the data survives on the Docker volume; + \item duplicate ingestion: sending the same telemetry event twice and checking for the \texttt{409} response. + \end{itemize} + \end{sloppypar} + + These checks stayed manual because they validate the deployed composition (containers, networking, environment variables, seed script) rather than single code units, and because exploring the API visually through Swagger UI was itself part of what we wanted to validate (NFR5). + + \section{Deployment}\label{deployment} + + Prerequisites: \textbf{Docker} with the Compose plugin, for the containerized setup, or \textbf{Node.js $\geq$ 24.18} plus a local \textbf{MongoDB 8}, should one want to run a service directly. + + Starting from a fresh clone, the Core REST Service stack comes up like this: + + \begin{enumerate} + \item \texttt{cd microservices/core-rest-service \&\& cp .env.example .env}: then set at least \texttt{MONGO\_URI}, \texttt{JWT\_SECRET} and \texttt{SERVICE\_TOKEN}. All configuration is passed through environment variables; nothing is hard-coded. + \item From the repository root, run \texttt{docker compose -f docker/docker-compose.yml up -d}: it starts MongoDB (with a named volume for persistence) and the Core REST Service. + \item Expected outcome: \texttt{GET http://localhost:3000/api/health} answers \texttt{200} with the service status, \texttt{GET /api/ready} confirms the database connection, and Swagger UI is available at \texttt{http://localhost:3000/api/docs}. + \item Seed the first admin user: \texttt{npm run seed:admin} with the \texttt{ADMIN\_*} variables set (the script prompts before overwriting an existing admin). + \end{enumerate} + + The MQTT side of the system (broker, Coordinator, simulators) has its own compose file: \texttt{docker compose -f}\allowbreak{} \texttt{docker/docker-compose.simulators.yml up -d} starts Mosquitto, one Coordinator and one simulator; adding more machines just means replicating the simulator block with a different \texttt{MACHINE\_ID}. + + The Core REST Service image comes from a \textbf{multi-stage Dockerfile} based on \texttt{node:24.18.0-alpine}: a shared base stage copies the package manifests, a \texttt{development} target installs every dependency, and a \texttt{production} target installs only the runtime ones (\texttt{npm ci --omit=dev}). + + The compose file picks the target through \texttt{build.target}, so the very same Dockerfile serves both environments. + + \begin{sloppypar} + Inside the compose network, services reach each other by name (\texttt{mongodb://mongo:27017}, \texttt{mqtt://mqtt-broker:1883}); only the API (3000), MongoDB (27017) and the broker (1883) get published on the host, purely for development convenience. + \end{sloppypar} + + \section{User Guide}\label{user-guide} + + Right now, the system is used through the interactive API documentation (Swagger UI), which acts as the user interface (\cref{fig:swagger-overview}): + + \begin{sloppypar} + \begin{enumerate} + \item Start the stack and seed the admin as described in \cref{deployment}. + \item Open \texttt{http://localhost:3000/api/docs}. + \item Log in: call \texttt{POST /api/auth/login} with the admin email and password; copy the \texttt{accessToken} from the response (\cref{fig:swagger-login}). + \item Click \emph{Authorize} and paste the token: from now on every request is authenticated. + \item Typical workflow: create an area (\texttt{POST /api/areas}), create a machine inside it (\texttt{POST /api/machines}), turn it on (\texttt{PATCH /api/machines/\{id\}/state}\allowbreak{} with \texttt{\{"currentState":}\allowbreak\texttt{ "operational"\}}), then browse its telemetry (\texttt{GET /api/telemetry?machineId=...}) as it arrives from the pipeline (\cref{fig:swagger-telemetry}). + \item User administration (create operators, deactivate accounts) is available to admins under \texttt{/api/users}. + \end{enumerate} + \end{sloppypar} + + You can see the outcomes directly in Swagger UI: created resources come back with their identifiers, invalid operations return structured errors (\texttt{code} and \texttt{message}), and forbidden operations return \texttt{403} when attempted with an operator token. + + In \cref{fig:swagger-telemetry} the first event returned is an anomalous reading: the operating temperature (112) is outside the normal range declared in the machine specifications, so the event is marked with \texttt{isAnomaly: true} and the anomalous sensor shows up in \texttt{details}. + + \begin{figure} + \centering + \includegraphics[width=0.85\textwidth]{figures/screenshot/swagger-overview} + \caption{Swagger UI at \texttt{/api/docs}: the endpoints of the Core REST Service.} + \label{fig:swagger-overview} + \end{figure} + + \begin{figure} + \centering + \includegraphics[width=0.85\textwidth]{figures/screenshot/swagger-login} + \caption{Login executed from Swagger UI: the response contains the JWT and the user profile.} + \label{fig:swagger-login} + \end{figure} + + \begin{figure} + \centering + \includegraphics[width=0.85\textwidth]{figures/screenshot/swagger-telemetry} + \caption{Telemetry history queried from Swagger UI; the most recent event is marked as an anomaly.} + \label{fig:swagger-telemetry} + \end{figure} + + \section{Self-evaluation}\label{self-evaluation} + + \subsection{David Cohen} + + \subsection{Giulia Nardicchia} + + \section{Future works}\label{future-works} + \begin{itemize} - \item Are there budget constraints for development, deployment, or operation? - \item Is minimizing resource usage important? + \item \textbf{Improve Scalability}: the current design is already horizontally scalable, but the Coordinator is a single instance; adding more replicas would require a distributed consumer group on the broker, and a way to avoid multiple replicas trying to update the same machine state at the same time. + \item \textbf{Liveness-driven state}: using missing heartbeats to automatically move a machine to \emph{off} after a timeout, closing the loop between the heartbeat channel and the state machine. + \item \textbf{More anomaly policies}: since the anomaly detector is already policy-based, adding new, more situational rules (per-sensor policies, trends over a time window instead of single readings) only means a local change inside the Coordinator. + \item \textbf{High availability}: a MongoDB replica set for data redundancy, and several stateless replicas of the Core REST Service behind a load balancer; JWT and statelessness already make the service replica-ready. \end{itemize} - \end{itemize} -\end{guideline} - -\section{Design}\label{design} - -This chapter explains the strategies used to meet the requirements identified in the analysis. -% -Ideally, the design should be the same, regardless of the technological choices made during the implementation phase. - -\begin{quote} -You can re-arrange the sections as you prefer, but all the sections must be present in the end -\end{quote} - -\noindent -\textbf{Important:} try to motivate your design choices in relation to the requirements and features identified -in \cref{requirements} and \cref{ds-features}. - -\subsection{Architecture}\label{architecture} - -\begin{itemize} - \item Which architectural style? - % - \begin{itemize} - \item why? - \end{itemize} -\end{itemize} - -\subsection{Infrastructure}\label{infrastructure} - -\begin{itemize} - \item are there \emph{infrastructural components} that need to be introduced? \emph{how many}? - % - \begin{itemize} - \item e.g.~\emph{clients}, \emph{servers}, \emph{load balancers}, - \emph{caches}, \emph{databases}, \emph{message brokers}, - \emph{queues}, \emph{workers}, \emph{proxies}, \emph{firewalls}, - \emph{CDNs}, \emph{etc.} - \end{itemize} - - \item how do components \emph{distribute} over the network? \emph{where}? - % - \begin{itemize} - \item e.g.~do servers / brokers / databases / etc. sit on the same - machine? on the same network? on the same datacenter? on the same - continent? - \end{itemize} - - \item how do components \emph{find} each other? - % - \begin{itemize} - \item how to \emph{name} components? - \item e.g.~DNS, \emph{service discovery}, \emph{load balancing}, - \emph{etc.} - \end{itemize} -\end{itemize} - -\begin{quote} -Component diagrams are welcome here -\end{quote} - -\subsection{Modelling}\label{modelling} - -\begin{itemize} - \item which \textbf{domain entities} are there? - % - \begin{itemize} - \item e.g.~\emph{users}, \emph{products}, \emph{orders}, \emph{etc.} - \end{itemize} - - \item how do \emph{domain entities} \textbf{map to} \emph{infrastructural components}? - % - \begin{itemize} - \item e.g.~state of a video game on central server, while inputs/representations on clients - \item e.g.~where to store messages in an IM app? for how long? - \end{itemize} - - \item which \textbf{domain events} are there? - % - \begin{itemize} - \item e.g.~\emph{user registered}, \emph{product added to cart}, \emph{order placed}, \emph{etc.} - \end{itemize} - - \item which sorts of \textbf{messages} are exchanged? - % - \begin{itemize} - \item e.g.~\emph{commands}, \emph{events}, \emph{queries}, \emph{etc.} - \end{itemize} - - \item what information does the \textbf{state} of the system comprehend - % - \begin{itemize} - \item e.g.~\emph{users' data}, \emph{products' data}, \emph{orders' data}, \emph{etc.} - \end{itemize} -\end{itemize} - -\begin{quote} -Class diagram are welcome here -\end{quote} - -\subsection{Interaction}\label{interaction} - -\begin{itemize} - \item how do components \emph{communicate}? \emph{when}? \emph{what}? - \item \emph{which} \textbf{interaction patterns} do they enact? -\end{itemize} - -\begin{quote} -Sequence diagrams are welcome here -\end{quote} - -\subsection{Behaviour}\label{behaviour} - -\begin{itemize} - \item how does \emph{each} component \textbf{behave} individually (e.g.~in \emph{response} to \emph{events} or messages)? - \begin{itemize} - \item some components may be \emph{stateful}, others \emph{stateless} - \end{itemize} - - \item which components are in charge of updating the \textbf{state} of the system? \emph{when}? \emph{how}? -\end{itemize} - -\begin{quote} -State diagrams are welcome here -\end{quote} - -\subsection{Data and Consistency Issues}\label{data-and-consistency-issues} - -\begin{itemize} - \item Is there any data that needs to be stored? - % - \begin{itemize} - \item \emph{what} data? \emph{where}? \emph{why}? - \end{itemize} - - \item how should \emph{persistent data} be \textbf{stored}? - % - \begin{itemize} - \item e.g.~relations, documents, key-value, graph, etc. - \item why? - \end{itemize} - - \item Which components perform queries on the database? - % - \begin{itemize} - \item \emph{when}? \emph{which} queries? \emph{why}? - \item concurrent read? concurrent write? why? - \end{itemize} - - \item Is there any data that needs to be shared between components? - % - \begin{itemize} - \item \emph{why}? \emph{what} data? - \end{itemize} -\end{itemize} - -\subsection{Fault-Tolerance}\label{fault-tolerance} - -\begin{itemize} - \item Is there any form of data \textbf{replication} / federation / sharing? - % - \begin{itemize} - \item \emph{why}? \emph{how} does it work? - \end{itemize} - - \item Is there any \textbf{heart-beating}, \textbf{timeout}, \textbf{retry mechanism}? - % - \begin{itemize} - \item \emph{why}? \emph{among} which components? \emph{how} does it work? - \end{itemize} - - \item Is there any form of \textbf{error handling}? - % - \begin{itemize} - \item \emph{what} happens when a component fails? \emph{why}? \emph{how}? - \end{itemize} -\end{itemize} - -\subsection{Availability}\label{availability} - -\begin{itemize} - \item Is there any \textbf{caching} mechanism? - % - \begin{itemize} - \item \emph{where}? \emph{why}? - \end{itemize} - - \item Is there any form of \textbf{load balancing}? - % - \begin{itemize} - \item \emph{where}? \emph{why}? - \end{itemize} - - \item In case of \textbf{network partitioning}, how does the system behave? - % - \begin{itemize} - \item \emph{why}? \emph{how}? - \end{itemize} -\end{itemize} - -\subsection{Security}\label{security} - -\begin{itemize} - \item Is there any form of \textbf{authentication}? - % - \begin{itemize} - \item \emph{where}? \emph{why}? - \end{itemize} - - \item Is there any form of \textbf{authorization}? - % - \begin{itemize} - \item which sort of \emph{access control}? - \item which sorts of users / \emph{roles}? which \emph{access rights}? - \end{itemize} - - \item Are \textbf{cryptographic schemas} being used? - % - \begin{itemize} - \item e.g.~token verification, - \item e.g.~data encryption, etc. - \end{itemize} -\end{itemize} - -\section{Implementation}\label{implementation} - -Please report here all the implementation (technology-dependent) choices you made while implementing your design. - -\begin{quote} - If you run out of time for this project, you may consider leaving some aspect unimplemented, - and simply discuss how you would have implemented them. - % - In this case, better would be to discuss unimplemented features in \cref{future-works}. -\end{quote} - -\begin{itemize} - \item which \textbf{network protocols} to use? - % - \begin{itemize} - \item e.g.~UDP, TCP, HTTP, WebSockets, gRPC, XMPP, AMQP, MQTT, etc. - \end{itemize} - - \item how should \emph{in-transit data} be \textbf{represented}? - % - \begin{itemize} - \item e.g.~JSON, XML, YAML, Protocol Buffers, etc. - \end{itemize} - - \item how should \emph{databases} be \textbf{queried}? - % - \begin{itemize} - \item e.g.~SQL, NoSQL, etc. - \end{itemize} - - \item how should components be \emph{authenticated}? - % - \begin{itemize} - \item e.g.~OAuth, JWT, etc. - \end{itemize} - - \item how should components be \emph{authorized}? - % - \begin{itemize} - \item e.g.~RBAC, ABAC, etc. - \end{itemize} -\end{itemize} - -\subsection{Technological details}\label{technological-details} - -\begin{itemize} - \item any particular \emph{framework} / \emph{technology} being exploited goes here -\end{itemize} - -\section{Validation}\label{validation} - -\subsection{Automatic Testing}\label{automatic-testing} - -\begin{itemize} - \item how were individual components \textbf{\emph{unit}-test}ed? - - \item how was communication, interaction, and/or integration among components tested? - - \item how to \textbf{\emph{end-to-end}-test} the system? - % - \begin{itemize} - \item e.g.~production vs.~test environment - \end{itemize} - - \item for each test specify: - % - \begin{itemize} - \item rationale of individual tests - \item how were the test automated - \item how to run them - \item which requirement they are testing, if any - \end{itemize} -\end{itemize} - -\begin{quote} -recall that \emph{deployment} \textbf{automation} is commonly used to \emph{test} the system in \emph{production-like} environment -\end{quote} - -\begin{quote} -recall to test corner cases (crashes, errors, etc.) -\end{quote} - -\subsection{Acceptance test}\label{acceptance-test} - -\begin{itemize} - \item did you perform any \emph{manual} testing? - % - \begin{itemize} - \item what did you test? - \item why wasn't it automatic? - \end{itemize} -\end{itemize} - -\section{Deployment}\label{deployment} - -\begin{itemize} - \item should one install your software from scratch, how to do it? - % - \begin{itemize} - \item provide instructions - \item provide expected outcomes - \end{itemize} - - \item what software should be installed on the machines to run your project? which versions? - - \item should one set environment variables or configuration files? - - \item if you're using containerization (e.g.~Docker), - describe how you engineered your deployment scrips (e.g. \texttt{docker-compose.yml} files) -\end{itemize} - -\section{User Guide}\label{user-guide} - -\begin{itemize} - \item how to use your software? - % - \begin{itemize} - \item provide instructions - \item provide expected outcomes - \item provide screenshots if possible - \end{itemize} -\end{itemize} - -\section{Self-evaluation}\label{self-evaluation} - -\begin{itemize} - \item An individual section is required for each member of the group - \item Each member must self-evaluate their work, listing the strengths and weaknesses of the product - \item Each member must describe their role within the group as objectively as possible. -\end{itemize} - -It should be noted that each student is only responsible for their own section. - -\section{Future works}\label{future-works} - -Discuss possible future works, improvements, extensions, optimizations, etc. - -Also discuss here any unimplemented feature, and how you would have implemented it. - -\bibliographystyle{plain} -\bibliography{references} \end{document} diff --git a/figures/components.mmd b/figures/components.mmd new file mode 100644 index 0000000..8db4939 --- /dev/null +++ b/figures/components.mmd @@ -0,0 +1,19 @@ +flowchart TB + subgraph host["Docker network (single host)"] + subgraph sims["Machine Simulators (1..N)"] + direction LR + SIM1["machine-simulator-1"] + SIMN["machine-simulator-N"] + end + BROKER(["MQTT broker (Mosquitto)"]) + COORD["Coordinator Service"] + CORE["Core REST Service :3000"] + DB[("MongoDB :27017")] + end + CLIENT["HTTP clients\n(Swagger UI / Web GUI)"] + + sims -- "MQTT publish\ntelemetry + heartbeat" --> BROKER + BROKER -- "MQTT subscribe" --> COORD + COORD -- "HTTP + service token:\nPOST /api/telemetry\nPATCH /api/machines/:id/state" --> CORE + DB --- CORE + CLIENT -- "HTTP + JWT" --> CORE diff --git a/figures/components.pdf b/figures/components.pdf new file mode 100644 index 0000000..a56f061 Binary files /dev/null and b/figures/components.pdf differ diff --git a/figures/machine-states.mmd b/figures/machine-states.mmd new file mode 100644 index 0000000..5edc2ee --- /dev/null +++ b/figures/machine-states.mmd @@ -0,0 +1,7 @@ +stateDiagram-v2 + [*] --> off : machine created + off --> operational : turned on + operational --> off : turned off + operational --> anomaly : anomaly detected + anomaly --> operational : back to normal + anomaly --> off : turned off diff --git a/figures/machine-states.pdf b/figures/machine-states.pdf new file mode 100644 index 0000000..dbb0324 Binary files /dev/null and b/figures/machine-states.pdf differ diff --git a/figures/screenshot/swagger-login.png b/figures/screenshot/swagger-login.png new file mode 100644 index 0000000..195c359 Binary files /dev/null and b/figures/screenshot/swagger-login.png differ diff --git a/figures/screenshot/swagger-overview.png b/figures/screenshot/swagger-overview.png new file mode 100644 index 0000000..b3ecd66 Binary files /dev/null and b/figures/screenshot/swagger-overview.png differ diff --git a/figures/screenshot/swagger-telemetry.png b/figures/screenshot/swagger-telemetry.png new file mode 100644 index 0000000..2b3cc8f Binary files /dev/null and b/figures/screenshot/swagger-telemetry.png differ diff --git a/figures/telemetry-flow-ingestion.mmd b/figures/telemetry-flow-ingestion.mmd new file mode 100644 index 0000000..e779476 --- /dev/null +++ b/figures/telemetry-flow-ingestion.mmd @@ -0,0 +1,17 @@ +sequenceDiagram + participant S as Simulator + participant B as Broker + participant C as Coordinator + participant R as Core REST + participant M as MongoDB + + S->>B: publish telemetry + B->>C: deliver event + C->>C: validate + evaluate anomaly + C->>R: POST /telemetry (service token) + R->>M: insert (unique eventId) + alt duplicate eventId + R-->>C: 409 Conflict + else stored + R-->>C: 201 Created + end diff --git a/figures/telemetry-flow-ingestion.pdf b/figures/telemetry-flow-ingestion.pdf new file mode 100644 index 0000000..b1734ff Binary files /dev/null and b/figures/telemetry-flow-ingestion.pdf differ diff --git a/figures/telemetry-flow-state.mmd b/figures/telemetry-flow-state.mmd new file mode 100644 index 0000000..1f82e55 --- /dev/null +++ b/figures/telemetry-flow-state.mmd @@ -0,0 +1,15 @@ +sequenceDiagram + participant C as Coordinator + participant R as Core REST + participant M as MongoDB + actor U as User + + opt machine condition changed + C->>R: PATCH /machines/{id}/state + R->>R: check transition + R->>M: atomic update + R-->>C: 200 OK / 422 invalid + end + + U->>R: GET /telemetry?machineId=... (JWT) + R-->>U: paginated history diff --git a/figures/telemetry-flow-state.pdf b/figures/telemetry-flow-state.pdf new file mode 100644 index 0000000..0a1108a Binary files /dev/null and b/figures/telemetry-flow-state.pdf differ diff --git a/figures/universe.jpg b/figures/universe.jpg deleted file mode 100644 index ed19e7d..0000000 Binary files a/figures/universe.jpg and /dev/null differ