docs(readme): refresh per #422 (#580)

- Document the data model and end-to-end alert flow at the top, with a
  link to CONTRIBUTING.md for the full breakdown.
- Split Quick Tour into a user path (docker compose pull/up against the
  published image, no Poetry needed) and a contributor path (make run,
  which builds locally and requires Poetry).
- Fix the docs URL: 8080 -> 5050 to match docker-compose.yml.
- Drop the outdated Swagger screenshot from the v0.1.2 release.
- Remove the dead Heroku redoc badge (also fixes its brain=main typo).
- Reframe the Contributing section to highlight that CONTRIBUTING.md
  also covers data model, codebase tour and developer setup.

Author: Acruve15

README.md

@@ -4,9 +4,6 @@
   <a href="https://github.com/pyronear/pyro-api/actions?query=workflow%3Abuilds">
     <img alt="CI Status" src="https://img.shields.io/github/actions/workflow/status/pyronear/pyro-api/builds.yml?branch=main&label=CI&logo=github&style=flat-square">
   </a>
-  <a href="http://pyronear-api.herokuapp.com/redoc">
-    <img src="https://img.shields.io/github/actions/workflow/status/pyronear/pyro-api/builds.yml?brain=main&label=docs&logo=read-the-docs&style=flat-square" alt="Documentation Status">
-  </a>
   <a href="https://codecov.io/gh/pyronear/pyro-api">
     <img src="https://img.shields.io/codecov/c/github/pyronear/pyro-api.svg?logo=codecov&style=flat-square" alt="Test coverage percentage">
   </a>
@@ -32,21 +29,38 @@
 
 The building blocks of our wildfire detection & monitoring API.
 
+The API stores access metadata (Users, Cameras, Organizations), the core wildfire-monitoring workflow (Detections grouped into Sequences), and client integrations (Webhooks). End to end, an alert flows like this: an admin registers a user, the user registers a camera and mints a camera token, then the camera uploads a picture as a detection, which is grouped into a sequence over a dense time window. For the full data model, UML diagram, codebase tour and developer setup, see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
 ## Quick Tour
 
-### Running/stopping the service
+Two ways to run the stack, depending on whether you just want to use the API or to develop against it.
 
-You can run the API containers using this command:
+### As a user (no Poetry needed)
+
+Pull the published `ghcr.io/pyronear/alert-api` image and start the stack:
 
 ```shell
-make run
+cp .env.example .env
+docker compose pull
+docker compose up
 ```
 
-You can now navigate to `http://localhost:8080/docs` to interact with the API (or do it through HTTP requests) and explore the documentation.
+Then navigate to [http://localhost:5050/docs](http://localhost:5050/docs) to interact with the API and explore the OpenAPI documentation.
 
-![Swagger](https://github.com/pyronear/pyro-api/releases/download/v0.1.2/swagger_interface.png)
+To stop the service:
+```shell
+docker compose down
+```
+
+### As a contributor (builds locally, requires Poetry)
 
-In order to stop the service, run:
+```shell
+make run
+```
+
+This regenerates `requirements.txt` from `poetry.lock` and builds the backend image locally, so it requires [Poetry](https://python-poetry.org/docs/) to be installed. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full developer setup, tests, and migration workflow.
+
+To stop the service:
 ```shell
 make stop
 ```
@@ -59,28 +73,16 @@ make stop
 - [Docker](https://docs.docker.com/engine/install/)
 - [Docker compose](https://docs.docker.com/compose/)
 
-### Starting your service
+Contributors building the image locally also need [Poetry](https://python-poetry.org/docs/); see [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### First-time setup
 
-#### 1 - Clone the repository
 ```shell
 git clone https://github.com/pyronear/pyro-api.git && cd pyro-api
-```
-#### 2 - Set your environment variables
-First copy the example environment setup
-```shell
 cp .env.example .env
 ```
 
-#### 3 - Start the services
-
-```shell
-docker compose pull
-docker compose up
-```
-
-#### 4 - Check how what you've deployed
-
-You can now access your backend API at [http://localhost:5050/docs](http://localhost:5050/docs)
+Then run the stack as described in the [Quick Tour](#quick-tour) above.
 
 
 ## More goodies
@@ -94,7 +96,7 @@ This project is a REST-API, and you can interact with the service through HTTP r
 
 Any sort of contribution is greatly appreciated!
 
-You can find a short guide in [`CONTRIBUTING`](CONTRIBUTING.md) to help grow this project!
+[`CONTRIBUTING.md`](CONTRIBUTING.md) covers more than the contribution guidelines: it also documents the data model, codebase structure, developer setup, testing workflow and database migrations. Start there if you want to understand how the project is organised.