diff --git a/README-dev.md b/README-dev.md
new file mode 100644
index 00000000..0e51135d
--- /dev/null
+++ b/README-dev.md
@@ -0,0 +1,47 @@
+README-dev
+==========
+
+# modules' description
+
+## Main
+
+swh.web.ui.main: Start the server or the dev server
+
+## Layers
+
+Folder swh/web/ui/:
+
+- api            main api endpoints definition (api)
+- views          main ui endpoints (web app)
+- service        Orchestration layer used by api/view module.
+                 In charge of communication with `backend` to retrieve
+                 information and conversion for the upper layer.
+- backend        Lower layer in charge of communication with swh storage.
+                 Used by `service` module.
+
+In short:
+1. views -depends-> api -depends-> service -depends-> backend     ----asks----> swh-storage
+2. views <- api <- service <- backend                             <----rets---- swh-storage
+
+## Utilities
+
+Folder swh/web/ui/:
+
+- apidoc         Browsable api functions.
+- exc            Exception definitions.
+- errorhandler   Exception (defined in `exc`) handlers.
+                 Use at route definition time (`api`, `views`).
+- renderers      Rendering utilities (html, json, yaml, data...).
+                 Use at route definition time (`api`, `views`).
+- converters     conversion layer to transform swh data to serializable data.
+                 Used by `service` to convert data before transmitting to `api` or `views`.
+- query          Utilities to parse data from http endpoints.
+                 Used by `service`
+- upload         Utility module to deal with upload of data to webapp or api.
+                 Used by `api`
+- utils          Utilities used throughout swh-web-ui.
+
+
+## TODO
+
+dot files to generate the dependencies drawing