Merge pull request #60 from igloo-4002/architecture

Add architecture info and more readme

ARCHITECTURE.md

@@ -0,0 +1,39 @@
+# Architecture
+
+`urbanflo-sumo-server` acts as the backend to UrbanFlo, and is responsible for communicating with [SUMO](https://sumo.dlr.de) which is the simulation engine we use, as well as storing simulation files. 
+
+![](docs/images/urbanflo-architecture.png)
+
+The server itself mostly adopts a controller-server-repository architecture. The controller is responsible for defining API endpoints for the frontend, which it communicates using WebSocket for the simulation stream, and REST for pretty much anything else (e.g. uploading a document). The storage service serves as an intermediate between the controller and the filesystem, while `SimulationInstance` is responsible for interacting with SUMO via the [TraCI library](https://sumo.dlr.de/docs/Libtraci.html).
+
+![](docs/images/urbanflo-backend.png)
+
+## Code map
+
+### Package `config`
+
+This package contains classes for Spring configuration, such as `WebSocketConfig` for WebSocket configuration.
+
+### Package `controller`
+
+Contains all controller classes.
+
+### Package `jackson`
+
+Contains custom Jackson serializers and deserializers, such as `UnixDoubleTimestampDeserializer` which deserializes Unix timestamps encoded as `Double` to Java `OffsetDateTime`.
+
+### Package `model`
+
+Contains model classes for various things, including API bodies and responses as well as SUMO data.
+
+### Package `netconvert`
+
+Contains any code related to [`netconvert`](https://sumo.dlr.de/docs/netconvert.html) which is a commandline SUMO utility for converting network data.
+
+### Package `simulation`
+
+Any code for running and managing simulations, such as `SimulationInstance` which contains a running simulation instance.
+
+### Package `storage`
+
+Anything related to storage, such as `FilesystemStorageService` which is our current implementation of the storage service.

README.md

@@ -1,5 +1,9 @@
 # urbanflo-sumo-server
 
+![CI Status](https://img.shields.io/github/actions/workflow/status/igloo-4002/urbanflo-sumo-server/ci.yml?style=flat-square)
+![Docker Build Status](https://img.shields.io/github/actions/workflow/status/igloo-4002/urbanflo-sumo-server/docker.yml?style=flat-square&label=docker)
+![Licence badge](https://img.shields.io/github/license/igloo-4002/urbanflo-sumo-server?style=flat-square)
+
 Interacts between [SUMO](https://www.eclipse.org/sumo/) and Urbanflo app.
 
 ## Development
@@ -9,6 +13,7 @@ Interacts between [SUMO](https://www.eclipse.org/sumo/) and Urbanflo app.
 - [JDK 17](https://adoptium.net/temurin/releases/)
 - [Kotlin](https://kotlinlang.org/docs/getting-started.html)
 - [Gradle](https://gradle.org/install/) (optional - wrapper included in repository)
+- [SUMO](https://sumo.dlr.de/docs/Downloads.php) with `libtracijni` library
 
 ### Building
 
@@ -40,3 +45,40 @@ See [this issue](https://github.com/eclipse/sumo/issues/13702) to learn more
 ```shell
 java -jar build/libs/urbanflo-sumo-server-0.0.1-SNAPSHOT.jar
 ```
+
+## Configuration
+
+### TraCI configuration
+
+You'll need `libtracijni` to be in the Java library path, or you'll get `UnsatisfiedLinkError` when starting the server. You can do this by either adding `$LIBTRACI_LIB` to `PATH` or passing `-Djava.library.path=$LIBTRACI_LIB` to the `java` command, where `$LIBTRACI_LIB` is the location of  `libtracijni` binary, such as `$SUMO_HOME/bin` if you used the official installation method on Linux. Consult the [SUMO docs](https://sumo.dlr.de/docs/Libtraci.html#java) for more information.
+
+### Spring profiles
+
+There are 2 configuration profiles, the default one and `prod`. The only difference is `prod` launches the server at port 80 while the default one uses port 8080.
+
+You can select `prod` profile by passing `-Dspring.profiles.active=prod` to `java` command.
+
+### Environment variables
+
+- `URBANFLO_FRONTEND_URL`: sets the frontend URL for CORS endpoint. Defaults to `http://localhost:5173` and is ignored when `URBANFLO_ALLOW_ALL_CORS_ORIGINS` is `true`
+- `URBANFLO_ALLOW_ALL_CORS_ORIGINS`: if set to `true`, the server will accept all CORS origins. Defaults to `false`.
+
+## Troubleshooting
+
+### Build failed because of `UnsatisfiedLinkError`
+
+See the [TraCI configuration](#traci-configuration) section on how to add `libtracijni` to Java library path.
+
+Alternatively you can skip testing by passing `-x test` to gradle.
+
+### Every request from frontend results in a CORS error
+
+You need to configure CORS for your setup. See [environment variables](#environment-variables) for more information.
+
+## Architecture 
+
+See [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Licence
+
+Licensed under [MIT License](LICENSE.txt).