TODO
The following section focuses on the development part of the project, including prerequisites, how to build and run the code, and how to contribute.
The web application runs on Node.js version 20.
Install the dependencies inside the web directory with:
npm installThe server application is written in Go and uses the version 1.22.
To run the application in containers, the Docker Engine is expected to be installed.
The Android application targets Android SDK 34.
Install Android Studio before you start contributing to the Android project.
In the project root directory, there is a Makefile that contains some targets to help develop and build the web and server applications.
Build and run both applications in a Docker container:
make upOr, if the goal is to run each application independently, see the following steps.
-
Start the web application in a development context:
make dev-web
-
Update the server configuration file, especially regarding the database connection string
-
To run the database locally, use the Docker Compose file:
docker compose up database
-
-
Start the server application in a development context:
make dev-server
The web application can be found in the web directory. It uses Svelte.
The web application contains several scripts to lint, build and run the project. To check the available scripts, run the following command inside the web directory:
npm runThe server application can be found in the server directory. It contains the Go code that serves the following routes:
| Route | Description |
|---|---|
| / | Web Application |
| /api | Rest API |
| /api/docs/ui | Swagger UI |
The server contains a Makefile that defines a set of tasks that can be run to help with development. The available targets can be checked by running the following command inside the server directory:
make helpTo serve the web application, the server expects the web static files to be in the dist/web directory.
The Rest API is documented in a Swagger Specification file (ecomap.yml) in the api/swagger directory. This file is also used by the server to generate the API models and server boilerplate code to handle the HTTP API (see the generate-oapi Makefile target).
Inside the api/swagger directory, there is also a ui folder that contains the Swagger UI that is served by the server to present the Rest API documentation. See the README.md file in api/swagger for more information.
The server application requires a PostgreSQL database to manipulate the persistent data. There is a Docker Compose file (docker-compose.yml) in the project root directory that already contains a database service that can be run locally.
The database migrations can be found in database/migrations in the server directory. When the server starts, it will make sure that the database is running the configured migration version. This behavior can also be configured and disabled if necessary.
Note that there is a configuration file in the server directory that contains some placeholder variables that allow the server to be configured. By default, the server reads the config.yml file, but this can be overridden by setting the CONFIG_FILE environment variable with a path to a valid configuration file in any other directory.
The Android application can be found in the android directory.
Use gradlew to lint, build and run the project from the command line.
The Android application uses the Google Maps SDK for Android. Create a secrets.properties file in the android directory with the following content:
MAPS_API_KEY=<REPLACE_WITH_YOUR_API_KEY>
- The main branch contains the production code
- To develop a new feature or fix a bug, a new branch should be created based on the main branch
- The features and bugs should exist as a GitHub issue with an appropriate description
- The status of the issues can be seen in the associated GitHub project
- Git commits should follow conventional commits
- To merge the code into production, a pull request should be opened following the existing template to describe it, as well as the appropriate labels
- To merge the pull request, the code must pass all GitHub action checks, be approved by at least one of the code owners, and be squashed and merged
- After the code is merged into the main branch, there is a GitHub action that automatically builds and deploys the code to production
- To release a new version of the project, semantic versioning should be followed
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent