You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains the code of the new *openSenseMap* frontend running at [https://beta.opensensemap.org](https://beta.opensensemap.org).
3
+
This repository contains the code of the new _openSenseMap_ frontend running at [https://beta.opensensemap.org](https://beta.opensensemap.org).
4
4
5
-
Originally, the *openSenseMap* was built as part of the bachelor thesis of [@mpfeil](https://github.com/mpfeil) at the ifgi (Institute for Geoinformatics, University of Münster). Between 2016 and 2022 development was partly funded by the German Ministry of Education and Research (BMBF) in the projets senseBox and senseBox Pro. This version has been developed by [@mpfeil](https://github.com/mpfeil) and [@freds-dev](https://github.com/freds-dev).
5
+
Originally, the _openSenseMap_ was built as part of the bachelor thesis of [@mpfeil](https://github.com/mpfeil) at the ifgi (Institute for Geoinformatics, University of Münster). Between 2016 and 2022 development was partly funded by the German Ministry of Education and Research (BMBF) in the projets senseBox and senseBox Pro. This version has been developed by [@mpfeil](https://github.com/mpfeil) and [@freds-dev](https://github.com/freds-dev).
You can create a copy of `.env.example`, rename it to `.env` and set the values.
31
31
@@ -34,13 +34,140 @@ You can create a copy of `.env.example`, rename it to `.env` and set the values.
34
34
1. Clone the repo: `git clone https://github.com/openSenseMap/frontend`
35
35
2. Copy `.env.example` into `.env`
36
36
3. Run `npm install` to install dependencies
37
-
4. Run `npm run docker` to start the docker container running your local postgres DB
38
-
5. Run `npm run build`
39
-
6. Run `npm run dev` to start the local server
37
+
4. Optionally run `docker compose up` to start a docker container running your local postgres DB
38
+
- If it is the first time doing this, you may need to bootstrap the database by running `npm run db:setup`
39
+
- If you want some example data run `npm run db:seed`. **WARNING**: Do not run this on a production database. It will delete all existing data.
40
+
5. Run `npm run dev` to start the local server
40
41
41
42
### Contributing
42
43
43
-
We welcome all kind of constructive contributions to this project. Please have a look at [CONTRIBUTING](.github/CONTRIBUTING.md) if you want to do so.
44
+
We welcome all kind of constructive contributions to this project.
45
+
If you are planning to implement a new feature or change something, please create an issue first.
46
+
47
+
Afterwards follow these steps:
48
+
49
+
1. Fork this repository
50
+
2. Create your feature branch (`git checkout -b my-new-feature`)
51
+
3. Make and commit your changes
52
+
4. Push to the branch (`git push origin my-new-feature`)
53
+
5. Create a new pull request against this repository's `dev` branch, linking your issue.
54
+
55
+
#### How the repository is organized
56
+
57
+
```shell
58
+
├── app # main directory where most of the application code lives
59
+
│ ├── components # reusable/ general purpose components
60
+
│ ├── lib
61
+
│ ├── models
62
+
│ ├── routes # app/ api routes
63
+
│ ├── schema
64
+
│ └── utils
65
+
├── db # code for seeding/ migration of database
66
+
├── drizzle # database migrations
67
+
├── other
68
+
├── public # static assets
69
+
├── server
70
+
├── tests # automated tests, same structure as the app/ folder with tests placed according to the files they test
71
+
│ ├── routes # tests for (resource/ api) routes
72
+
├── types
73
+
├── ...
74
+
```
75
+
76
+
#### openSenseMap API
77
+
78
+
The api is implemented using [Remix resource routes](https://remix.run/docs/en/main/guides/resource-routes).
79
+
Resource routes may not export a component but only [loaders](https://remix.run/docs/en/main/route/loader) (for `GET` requests) and [actions](https://remix.run/docs/en/main/route/action) (for `POST`, `PUT`, `DELETE` etc) and therefore live in `.ts` (not `.tsx`) files.
80
+
All resource routes start with `api` (e.g. `api.user.ts` for `/api/user`).
81
+
82
+
The api logic is shared with the frontend. Therefore api routes should not implement the actual business logic of an endpoint. They are responsible for checking the request for validity and for transforming the data into the correct output format.
83
+
Logic should be implemented in corresponding services, that may be used by loaders/ actions of page routes that access the same functionality.
84
+
85
+
For example: User registration is possible from both the api and the frontend. The logic for it is implemented in `lib/user.service.ts` and it is being used by both `api.user.ts` (resource route) as well as `explore.register.tsx` (page route), preventing duplication of common logic while also providing the flexibility to adjust the outputs to the needs of the respective use case.
86
+
87
+
##### Documenting an API Route
88
+
89
+
The [swaggerJsdoc Library](https://www.npmjs.com/package/swagger-jsdoc) reads the JSDoc-annotated source code in the api-routes and generates an openAPI(Swagger) specification and is rendered using [Swaggger UI](https://swagger.io/tools/swagger-ui/). The [JSDoc annotations](https://github.com/Surnet/swagger-jsdoc) is usually added before the loader or action function in the API Routes. The documentation will then be automatically generated from the JSDoc annotations in all the api routes. When testing the api during development do not forget to change the server to [Development Server](http://localhost:3000).
90
+
91
+
##### JSDoc Example
92
+
93
+
Here's an example of how to document an API route using JSDoc annotations:
94
+
95
+
```javascript
96
+
/**
97
+
* @openapi
98
+
* /api/users/{id}:
99
+
* get:
100
+
* summary: Get user by ID
101
+
* description: Retrieve a single user by their unique identifier
102
+
* tags:
103
+
* - Users
104
+
* parameters:
105
+
* - in: path
106
+
* name: id
107
+
* required: true
108
+
* description: Unique identifier of the user
109
+
* schema:
110
+
* type: string
111
+
* example: "12345"
112
+
* responses:
113
+
* 200:
114
+
* description: User retrieved successfully
115
+
* content:
116
+
* application/json:
117
+
* schema:
118
+
* type: object
119
+
* properties:
120
+
* id:
121
+
* type: string
122
+
* example: "12345"
123
+
* name:
124
+
* type: string
125
+
* example: "John Doe"
126
+
* email:
127
+
* type: string
128
+
* example: "john.doe@example.com"
129
+
* createdAt:
130
+
* type: string
131
+
* format: date-time
132
+
* example: "2023-01-15T10:30:00Z"
133
+
* 404:
134
+
* description: User not found
135
+
* content:
136
+
* application/json:
137
+
* schema:
138
+
* type: object
139
+
* properties:
140
+
* error:
141
+
* type: string
142
+
* example: "User not found"
143
+
* 500:
144
+
* description: Internal server error
145
+
*/
146
+
exportasyncfunctionloader({ params }) {
147
+
const { id } = params;
148
+
149
+
try {
150
+
constuser=awaitgetUserById(id);
151
+
if (!user) {
152
+
thrownewResponse("User not found", { status:404 });
153
+
}
154
+
returnResponse.json({ user });
155
+
} catch (error) {
156
+
thrownewResponse("Internal server error", { status:500 });
157
+
}
158
+
}
159
+
```
160
+
161
+
This JSDoc annotation will automatically generate comprehensive API documentation including endpoint details, parameters, response schemas, and example values.
162
+
163
+
164
+
#### Testing
165
+
166
+
Tests are placed in the [tests/](./tests/) folder whose structure is similar to the [app/](./app/) folder.
167
+
When adding a test, use the same name as the file you are testing but change the file extension to `.spec.ts`, e.g. when creating tests for [`./app/utils`](./app/utils.ts) name the test file [`./tests/utils.spec.ts`](./tests/utils.spec.ts).
168
+
169
+
To run the tests, make sure you have a working database connection (e.g. by running `docker compose up` with the corresponding environment variables to use your local database).
0 commit comments