diff --git a/README.md b/README.md
index 1628e41..6f7f2eb 100644
--- a/README.md
+++ b/README.md
@@ -6,101 +6,195 @@
[](https://aperisolve.com/)
[](https://inventory.raw.pm/tools.html#Aperi'Solve)
-
+
+
+
+
+
-Try it now: https://www.aperisolve.com
+Try it now: **https://www.aperisolve.com**
- Support Aperi'Solve:
+Support Aperi'Solve:
-## What is Aperi'Solve?
-Aperi'Solve is a platform which performs steganalysis on images.
+---
-The platform uses *layer analysis*, "*zsteg*", "*steghide*", "*outguess*", "*exiftool*", "*binwalk*", "*foremost*" and "*strings*" for deeper steganography analysis.
+Aperi'Solve is an open-source steganalysis web platform that performs automated analysis on images to detect and extract hidden data using common steganography tools and techniques.
-
-
-### Why Aperi'Solve?
+Table of contents
+- [Key features](#key-features)
+- [Quick start (Docker)](#quick-start-docker)
+- [Development](#development)
+- [Adding a new analyzer](#adding-a-new-analyzer)
+- [Configuration & environment variables](#configuration--environment-variables)
+- [Architecture](#architecture)
+- [Troubleshooting & tips](#troubleshooting--tips)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
-Aperi'Solve has been created in order to have an "easy to use" platform which performs common steganalysis tests such as LSB or `steghide`. The platform is also a quick alternative for people who were note able to install tools like `zsteg` (ruby gem) properly.
+## Key features
-### Features
+- Visualize each bit layer (LSB and other layers) per image channel (R/G/B/Alpha).
+- Browse and download each bit-layer image.
+- Integrates and displays outputs from:
+ - zsteg (LSB text/data extraction)
+ - steghide (extraction with password)
+ - outguess (extraction with password)
+ - exiftool (metadata and geolocation)
+ - binwalk (embedded archives)
+ - foremost (carved files)
+ - pngcheck
+ - strings
+- Worker queue architecture for offloading heavy/slow analyzers (Redis + background workers).
+- Results stored for later browsing and download.
-Aperi'Solve is based on Python3 with Flask and PIL module, the platform supports the most common image formats like`.png`, `.jpg`, `.gif`, `.bmp`, `.jpeg`, `.jfif`, `.jpe`, `.tiff`...
+## Quick start (Docker)
-The platform allows you to:
-- **Visualize each bit layer** of each channel for a given image (ie. LSB of Red channel).
-- **Browse** and **Download each bit layer image**.
-- **Visualise `zsteg` information** such as text encoded on LSB
-- **Download `steghide` files** using a defined password
-- **Download `outguess` files** using a defined password
-- **Visualise `exiftool` information** such as geolocation or author
-- **Visualise `binwalk` information**
-- **Download `binwalk` files** such as ZIP file in PNG headers
-- **Download `foremost` files** such as ZIP file in PNG headers
-- **Visualise `pngcheck` output**
-- **Visualise `strings` output**
+In case you want to host your own version of https://www.aperisolve.com/.
-## Installation
-
-Even if Aperi'Solve is available at the URL https://www.aperisolve.com/, you can set up your own instance with the following command:
+Recommended: Docker + Docker Compose.
+Clone and start the full stack (production-like):
```bash
git clone https://github.com/Zeecka/AperiSolve.git
-cd aperisolve
+cd AperiSolve
docker compose up -d
```
-> Default will run on http://localhost:5000/
+Default: http://localhost:5000/
## Development
-
-Aperi'Solve platform is a *Flask* web service (python 3.11+) with python workers performing analysis.
-Jobs are stacked in a redis-queue, and image information is stored in a postgresql database.
-All services run inside Docker containers.
-
-### Adding new analyzer
-
-Adding new analyzer is easy.
-
-1. Copy and adapt the [template_analyzer.py](aperisolve/analyzers/template_analyzer.py) file with your name, ie. "myanalyzer.py".
-2. Add this analyzer to [workers.py](aperisolve/workers.py).
- - Import your function `from .analyzers.analyzer import analyze_myanalyzer`
- - Add the function to the `analyzers` variable, like other analyzers.
-3. Add your analyzer name to `TOOL_ORDER` in [aperisolve.js](aperisolve/static/js/aperisolve.js).
-
-### Tips
-
-Here is a batch of useful commands.
-
+Development compose:
```bash
-docker compose down -v # Remove the volume containings results
-docker compose -f compose.dev.yml up # Start application in developpement mode
-rm -rf aperisolve/results # Remove results from development mode
-docker exec -it postgres psql -U aperiuser -d aperisolve # Get postgresql shell
-docker exec -it aperisolve-web bash # Get a shell inside the running web app
+# development environment (hot reload and local volumes)
+docker compose -f compose.dev.yml up --build
```
-> Note, if you used [compose.dev.yml](compose.dev.yml), you must remove "results" when switching to [production Docker](compose.yml) setup.
+Useful commands:
+```bash
+# Stop and remove containers, networks and volumes (results are stored in a volume)
+docker compose down -v
-### Code quality
+# Enter web container shell
+docker exec -it aperisolve-web bash
-Python code follows the following linters:
+# Enter Postgres shell (from host)
+docker exec -it postgres psql -U aperiuser -d aperisolve
+```
-- Black
-- Flake8 (ignoring E203,E501,W503)
-- Pylint (ignoring W0718,R0903,R0801)
-- Mypy (ignoring unused-awaitable)
+Note: If switching between dev and production compose files, remove the `results` directory or mounted volume to avoid conflicts:
+```bash
+rm -rf aperisolve/results
+```
+### Adding a new analyzer
-GitHub CI will alert in case of failure.
+Adding a custom analyzer is straightforward:
+
+1. Create your analyzer file:
+ - Copy `aperisolve/analyzers/template_analyzer.py` -> `aperisolve/analyzers/myanalyzer.py`
+ - Implement function signature similar to:
+ ```python
+ # aperisolve/analyzers/myanalyzer.py
+ def analyze_myanalyzer(image_path: str, results_dir: str) -> dict:
+ """
+ Perform analysis on image located at image_path.
+ Produce outputs in results_dir and return a result dict (json-serializable).
+ """
+ # your analysis logic here
+ return {"name": "myanalyzer", "status": "ok", "outputs": [...]}
+ ```
+
+2. Register the analyzer in the worker pipeline:
+ - Edit `aperisolve/workers.py`:
+ ```python
+ # import
+ from .analyzers.myanalyzer import analyze_myanalyzer
+
+ # add to analyzers list (preserve the order)
+ analyzers = [
+ analyze_zsteg,
+ analyze_steghide,
+ # ...
+ analyze_myanalyzer,
+ ]
+ ```
+
+3. Add your analyzer to the UI order:
+ - Edit `aperisolve/static/js/aperisolve.js` and append `myanalyzer` to `TOOL_ORDER` so it appears in the frontend.
+
+4. Test locally: run the worker and submit jobs to ensure outputs are produced and displayed.
+
+Tips:
+- Keep analyzers idempotent and write outputs to the provided `results_dir`.
+- Return structured JSON so the frontend can render links/downloads automatically.
+
+## Configuration & environment variables
+
+Typical services:
+- Web app (Flask)
+- Workers (Python)
+- Redis (RQ)
+- PostgreSQL
+
+Main environment variables (examples):
+- DATABASE_URL=postgresql://aperiuser:password@postgres:5432/aperisolve
+- REDIS_URL=redis://redis:6379/0
+- SECRET_KEY=change_me
+- FLASK_ENV=production/development
+
+If using Docker Compose, defaults are set in the compose files. For production deployments, set secure secrets via your orchestrator or environment.
+
+## Architecture
+
+- Flask web framework
+- Background workers that run analyzers (queue via Redis)
+- PostgreSQL stores image metadata and job statuses
+- Docker-based deployment for isolation of analyzers and services
+
+This separation keeps heavy tools (binwalk, foremost, zsteg, etc.) isolated and avoids blocking the web worker.
+
+## Troubleshooting & tips
+
+- If analyzers don't produce output, check worker logs:
+ ```bash
+ docker compose logs -f aperisolve-worker
+ ```
+- To force re-analysis, remove results for the image (both file and in database) and re-submit the job.
+- Ensure system packages needed by native tools (binwalk, foremost) are available in the analyzer containers or host image.
## Roadmap
-- [ ] Zsteg extract / --all --> **Download `zsteg` files** such as mp3 encoded on LSB
-- [ ] Test on mobile
-- [ ] i18n
-- [ ] Rootless analyzers ?
+- [ ] zsteg: full extraction (--all) and download of discovered files (mp3, etc.)
+- [ ] Mobile-friendly UI / test on mobile
+- [ ] i18n (internationalization)
+- [ ] Rootless / unprivileged analyzers
+- [ ] Improve analyzer sandboxing (e.g., per-analyzer containers)
+
+## Contributing
+
+Contributions are welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Open a pull request describing your change
+
+Please follow the code style and run linters before submitting.
+The project adheres to:
+- Black
+- Flake8 (ignoring E203, E501, W503)
+- Pylint (ignoring W0718, R0903, R0801)
+- Mypy (ignoring unused-awaitable)
+
+CI will run these checks on each PR.
+
+## Security
+
+- If you discover a security issue, please report it privately to the repository owner instead of opening a public issue.
+
+## Credits
+
+Acknowledgements:
+- Thanks to contributors and the open-source community for the tools integrated (zsteg, steghide, binwalk, foremost, exiftool).