From 94e59ab8787faa877e06c10e85b7d2b1d3c21503 Mon Sep 17 00:00:00 2001
From: sdarbinyan <sdarbinyan@4pay.ru>
Date: Tue, 14 Jul 2026 12:22:21 +0400
Subject: [PATCH] docs(nginx): clarify SPA fallback and API proxy patterns in
 onboarding template

Drop the misleading trailing `=404` on try_files (index.html always exists
so it never triggered) and document, inline, the two ways a tenant's
frontend can reach its API (proxied /api vs absolute apiUrl) plus a note
that a 502/504 on refresh/back-navigation for an absolute-apiUrl tenant
(e.g. dexarmarket.ru -> api.dexarmarket.ru:445) is that backend's own
reverse proxy, not this file.
---
 nginx.conf | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/nginx.conf b/nginx.conf
index cbaf5ee..b6d2d38 100644
--- a/nginx.conf
+++ b/nginx.conf
@@ -7,7 +7,7 @@ server {
     
     # Angular routing - serve index.html for all routes
     location / {
-        try_files $uri $uri/ /index.html =404;
+        try_files $uri $uri/ /index.html;
     }
 
     # Static assets caching
@@ -55,7 +55,7 @@ server {
 
     # Angular routing
     location / {
-        try_files $uri $uri/ /index.html =404;
+        try_files $uri $uri/ /index.html;
     }
 
     # Proxy API calls to backend
@@ -99,6 +99,35 @@ server {
 # Replace NEWMARKETPLACE.EXAMPLE.COM, /var/www/newmarketplace, and the
 # api.newmarketplace.example.com:443 proxy target with the real values,
 # then rename this block's server_name/root before deploying.
+#
+# --- SPA routing (read before you skip this) ---
+# This is an Angular app with client-side routing (all page navigation - the
+# admin dashboard, project editor, catalog, product pages, etc. - happens in
+# the browser, not via new server requests). Every URL the app owns
+# (/:lang/backoffice/dashboard, /:lang/edit/general, /:lang/catalog/5, ...)
+# must fall through to index.html on a fresh request (page refresh, typed
+# URL, browser back/forward after a full reload) so Angular's router can take
+# over client-side. `try_files $uri $uri/ /index.html;` below is what makes
+# that work: nginx tries the literal file, then the directory, then falls
+# back to index.html for anything that isn't a real static asset. If you ever
+# see a raw nginx 404 page on refresh/back-navigation (not a blank app, an
+# actual nginx error page), this fallback is missing or misconfigured for
+# that server block - it is NOT an Angular or JS problem.
+#
+# --- Two ways the frontend talks to its API - pick one per tenant ---
+# 1) Proxied (what this template and the lovero.store block above do):
+#    the frontend calls a relative `/api/...` path, and nginx proxies it to
+#    the real backend below. Browser never sees the backend host/port.
+# 2) Direct (what the dexarmarket.ru production build does): the frontend's
+#    `environment.production.ts` sets `apiUrl`/`authApiUrl` to an absolute
+#    URL (e.g. `https://api.dexarmarket.ru:445`) and calls that directly -
+#    this nginx config is never involved in API calls at all for that tenant.
+# If a tenant using pattern (2) reports 502/504 Bad Gateway on refresh or
+# back-navigation, it is NOT this file - the app re-fires session-check and
+# bootstrap-load calls on every route change/refresh, and a 502/504 means the
+# *backend's own* reverse proxy/app server (the one fronting that absolute
+# apiUrl/authApiUrl host) is down, overloaded, or timing out. Check that
+# backend's own nginx/app logs, not this one.
 server {
     listen 80;
     server_name newmarketplace.example.com www.newmarketplace.example.com;
@@ -109,10 +138,12 @@ server {
     # Angular routing - serve index.html for all routes (client-side router
     # handles /edit, /:lang/edit/:section, etc. once index.html is served)
     location / {
-        try_files $uri $uri/ /index.html =404;
+        try_files $uri $uri/ /index.html;
     }
 
-    # Proxy API calls to backend
+    # Proxy API calls to backend - only needed if this tenant uses the
+    # relative `/api` pattern (see comment above); delete this block if the
+    # tenant's environment.*.ts uses an absolute apiUrl instead.
     location /api {
         proxy_pass https://api.newmarketplace.example.com:443;
         proxy_set_header Host api.newmarketplace.example.com;