diff --git a/README.md b/README.md
index cd7eb85..c855387 100644
--- a/README.md
+++ b/README.md
@@ -9,4 +9,8 @@ The platform is divided into 2 Node.js applications:
 - a Content Management System (CMS) located in the `/cms` folder
 - a client application located in the `/client` folder
 
-More detailed documentation and instructions on how to run the applications are available in each of the folders.
\ No newline at end of file
+More detailed documentation and instructions on how to run the applications are available in each of the folders.
+
+## Architecture
+
+![The front-end application accesses a Mapbox account, AWS S3 bucket and the CMS. The CMS relies on a PostgreSQL database. Everything but the Mapbox account are hosted on AWS. The general public can access the front-end application while administrators can access the CMS. Mapbox stores and serves the basemap, vector and some raster layers. AWS S3 stores and serves the pre-computed static and animated raster tiles. PostgreSQL stores data such as the locations, dataset metadata and layer confifiguration. It does not store any geospatial data.](./readme-architecture-diagram.png)
\ No newline at end of file
diff --git a/client/README.md b/client/README.md
index c403366..9c6851b 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1,36 +1,44 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# South Sudan Pilot − Client application
 
-## Getting Started
+## Dependencies
 
-First, run the development server:
+- Node.js (see version in [.nvmrc](https://github.com/Vizzuality/south-sudan-pilot/blob/staging/client/.nvmrc))
+- [Yarn 4](https://yarnpkg.com/) (see version in [package.json](https://github.com/Vizzuality/south-sudan-pilot/blob/staging/client/package.json))
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+## Install & run
+
+### Native execution
+
+Be sure to set the required environment variables before running the application - see the Environment variables section below for more details.
+
+To install the dependencies, use:
+
+```
+yarn
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+To run the application in development mode, use:
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```
+yarn dev
+```
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+To run the application in production mode, use:
 
-## Learn More
+```
+yarn build
+yarn start
+```
 
-To learn more about Next.js, take a look at the following resources:
+### Docker
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+This project includes 2 docker configuration files:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+- [Dockerfile](https://github.com/Vizzuality/south-sudan-pilot/blob/staging/client/Dockerfile) aimed at development environments (may require tuning to work on different environments)
+- [Dockerfile.prod](https://github.com/Vizzuality/south-sudan-pilot/blob/staging/client/Dockerfile.prod) aimed at production environments
 
-## Deploy on Vercel
+You can use either file to build a Docker image for this application. Be sure to set the required environment variables when running the container.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Environment variables
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+See [src/env.ts](https://github.com/Vizzuality/south-sudan-pilot/blob/staging/client/src/env.ts).
diff --git a/readme-architecture-diagram.png b/readme-architecture-diagram.png
new file mode 100644
index 0000000..082bd19
Binary files /dev/null and b/readme-architecture-diagram.png differ