updated documentation

# Best Practice Setup for Multi‑App Deployment with Centralized Nginx and Multiple Tornado Backends

This document summarizes the recommended architecture for deploying **multiple React frontends** and **multiple Tornado backends** behind a **single centralized Nginx reverse proxy**, using **Docker Compose** per app, and a **shared nginx-net** for communication.

---

## ✅ 1. Architecture Overview

Each app has:

- Its **own docker-compose.yml**

- Its own **frontend** (e.g., React)

- Its own **backend** (Tornado)

- Both are attached to the **central nginx-net** so Nginx can route to them

- Backend service name may be reused (e.g., `tornado-backend`)

- Backend gets a **unique network alias** for Nginx routing

---

## ✅ 2. URL Namespace Structure (Recommended)

Each app uses a dedicated URL prefix:

```

/<app-name>/               → Frontend

/<app-name>/api/           → Backend API

```

Examples:

### App 1: Blog

```

/aidaho-blog-demo/

/aidaho-blog-demo/api/

```

### App 2: Shop

```

/aidaho-shop/

/aidaho-shop/api/

```

### App 3: Analytics

```

/aidaho-analytics/

/aidaho-analytics/api/

```

This structure:

✅ Prevents routing conflicts  

✅ Keeps apps isolated  

✅ Works perfectly with React Router  

✅ Makes backend routing trivial  

---

## ✅ 3. Tornado Backend Routes

Backend should **not include the app prefix**.

Use simple API routes:

```python

(r"/api/get-user-role", GetUserRoleHandler),

(r"/api/login", LoginHandler),

(r"/api/logout", LogoutHandler),

```

The app prefix is handled by **Nginx**, not by the backend.

---

## ✅ 4. Frontend Configuration

Each frontend app should have:

### `homepage` in package.json:

```json

"homepage": "/aidaho-blog-demo"

```

### config.js:

```js

const isDev = !process.env.NODE_ENV || process.env.NODE_ENV === "development";

const config = {

  backendBaseUrl: isDev

    ? ""                        // CRA proxy handles routing in dev

    : "/aidaho-blog-demo/api", // Production backend path prefix

};

export default config;

```

### API calls:

```js

fetch(`${config.backendBaseUrl}/get-user-role`);

```

---

## ✅ 5. Production Nginx Configuration

Example for THREE apps:

```nginx

# ----------------------------

# Blog application

# ----------------------------

location /aidaho-blog-demo/api/ {

    proxy_pass http://blog-backend:8888/api/;

}

location /aidaho-blog-demo/ {

    alias /usr/share/nginx/html/aidaho-blog-demo/;

    try_files $uri $uri/ /aidaho-blog-demo/index.html;

}

# ----------------------------

# Shop application

# ----------------------------

location /aidaho-shop/api/ {

    proxy_pass http://shop-backend:8888/api/;

}

location /aidaho-shop/ {

    alias /usr/share/nginx/html/aidaho-shop/;

    try_files $uri $uri/ /aidaho-shop/index.html;

}

# ----------------------------

# Analytics application

# ----------------------------

location /aidaho-analytics/api/ {

    proxy_pass http://analytics-backend:8888/api/;

}

location /aidaho-analytics/ {

    alias /usr/share/nginx/html/aidaho-analytics/;

    try_files $uri $uri/ /aidaho-analytics/index.html;

}

```

Each backend uses a **network alias** to give Nginx a stable hostname.

---

## ✅ 6. Docker Compose (per app)

**blog-app/docker-compose.yml**

```yaml

services:

  tornado-backend:

    build: ./backend

    expose:

      - "8888"

    networks:

      nginx-net:

        aliases:

          - blog-backend    # ✅ stable Nginx hostname

  react-frontend:

    build: ./frontend

    networks:

      - nginx-net

networks:

  nginx-net:

    external: true

```

Other apps follow the same pattern:

- `shop-backend`

- `analytics-backend`

- …

✅ All apps reuse the same backend service name `tornado-backend`  

✅ All have different **network aliases**  

✅ Nginx accesses them by alias

---

## ✅ 7. Development Environment

Use React’s CRA proxy:

```json

"proxy": "http://tornado-backend:8888"

```

Backend routes remain `/api/...`.

Frontend dev server runs on:

```

http://localhost:3000

```

Backend in Docker is reachable via proxy; no CORS needed.

---

## ✅ 8. Key Recommendations Recap

| Component | Best Practice |

|----------|---------------|

| Backend service name | ✅ Can reuse `tornado-backend` across apps |

| Backend DNS names | ✅ Use network aliases (`blog-backend`, `shop-backend`) |

| Backend port | ✅ All backends can use port `8888` internally |

| Nginx routing | ✅ Route via `/app-name/api/` |

| Frontend route base | ✅ `/app-name/` |

| Backend route base | ✅ `/api/` |

| Compose networks | ✅ All apps join `nginx-net` |

| CORS | ✅ Only needed for production, not with CRA proxy |

---

# ✅ Final Diagram

```

                  ┌───────────────────────────────┐

                  │           NGINX               │

                  │  https://domain.com           │

                  ├────────────────────────────────┤

                  │  /aidaho-blog-demo/     → React (blog)      │

                  │  /aidaho-blog-demo/api/ → blog-backend       │

                  │                                                   │

                  │  /aidaho-shop/         → React (shop)      │

                  │  /aidaho-shop/api/     → shop-backend       │

                  │                                                   │

                  │  /aidaho-analytics/    → React (analytics) │

                  │  /aidaho-analytics/api/→ analytics-backend  │

                  └───────────────────────────────┘

                                │

                                ▼

                       Docker Network: nginx-net

                (all backends and frontends attached)

```

---

If you want this document expanded into a complete **deployment guide**, I can generate that too.

# React Tornado Stage No 4

## Development

- App/project layer: Containerized services:

  - Tornado backend

  - React frontend (development server)

  - PostgreSQL database

  - DB admin tool (optional)

  - => All these app/project specific services are connected via a docker network.

- Machine layer: localhost

  -  React frontend, i.e., port 3000 is reachable from the localhost

## Deployment

- App/project specific containerized services:

  - Tornado backend

  - PostgreSQL database

  - => All these app/project specific services are connected via a docker network.

- Machine layer: 

  - Containerized nginx service