thundercode commited on
Commit
f172bd1
Β·
verified Β·
1 Parent(s): 55f002c

release: add docs/architecture/02-deployment-topology.md

Browse files
docs/architecture/02-deployment-topology.md CHANGED
@@ -8,7 +8,7 @@
8
 
9
  > **One-paragraph summary.** SatQuery AI is deployed as **four tiers**: a static browser client on
10
  > **Cloudflare Pages** (`satquery.pages.dev`), a thin stateless **gateway/orchestrator on Render**
11
- > (`satquery-orchestrator` at `satquery-backend-m4yv.onrender.com`), a **FastAPI inference service inside
12
  > a GitHub Codespace** (FastAPI on port `8000`), and **Hugging Face** as the project/model-presence tier.
13
  > The gateway does not dial into the Codespace. Instead the Codespace **dials out** to the gateway over a
14
  > long-poll **tunnel** (`POST /tunnel/agent`), because a *forwarded* Codespace port returns **HTTP 302**
@@ -28,7 +28,7 @@ USER / BROWSER
28
  Cloudflare Pages β€” static frontend satquery.pages.dev
29
  β”‚ HTTPS, JSON, /api/*
30
  β–Ό
31
- Render β€” orchestrator / API gateway satquery-backend-m4yv.onrender.com
32
  β”‚ service: satquery-orchestrator
33
  β”‚ outbound long-poll (POST /tunnel/agent) ← direction is INVERTED
34
  β–Ό
@@ -59,7 +59,7 @@ flowchart LR
59
  |---|---|---|---|---|
60
  | Browser | the user's machine | `frontend/` static JS | **No** β€” never | no |
61
  | Static | Cloudflare Pages, `satquery.pages.dev` | HTML/CSS/JS only | **No** | no |
62
- | Gateway | Render, `satquery-orchestrator`, `satquery-backend-m4yv.onrender.com` | `deploy/render/main.py` (`SatQuery-Backend` in production) | **Yes** β€” `GITHUB_TOKEN` (and `HF_TOKEN` if the proxy path is used) | no |
63
  | Inference | GitHub Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port `8000` | `app/space_app.py::build_space_app()` via `deploy/codespace/serve.py` | no gateway secrets | ephemeral asset store only |
64
  | Presence | Hugging Face (`hf/`) | project README / model cards | no | no |
65
 
@@ -732,7 +732,7 @@ This is the same class of trap as Β§9.4 below: **the working copy is not the dep
732
 
733
  ### 7.1 The measured payload
734
 
735
- Probed live on 2026-09-25 against `https://satquery-backend-m4yv.onrender.com/api/health`
736
  (`release/repo/docs/DEPLOYMENT.md` Β§2):
737
 
738
  ```json
@@ -744,7 +744,7 @@ Probed live on 2026-09-25 against `https://satquery-backend-m4yv.onrender.com/ap
744
  ```
745
 
746
  Exact command used elsewhere in the project's evidence register:
747
- `curl --noproxy '*' https://satquery-backend-m4yv.onrender.com/api/health`
748
  (`docs/FINAL_DELIVERY_REPORT.md` Β§4).
749
 
750
  ### 7.2 Field-by-field
@@ -1161,7 +1161,7 @@ else
1161
  The hub URL is a defaulted variable, so a renamed Render service can be overridden in the Codespace:
1162
 
1163
  ```bash
1164
- export SATQUERY_HUB_URL="${SATQUERY_HUB_URL:-https://satquery-backend-m4yv.onrender.com}"
1165
  ```
1166
 
1167
  ### 9.3 The asset-upload environment, and why `/tmp` is correct
@@ -1229,7 +1229,7 @@ to a barely-chosen location."*
1229
  | Component | Repository | Branch | Revision | Host |
1230
  |---|---|---|---|---|
1231
  | Frontend | `SatQuery-Frontend` | `main` | **`2d7ae53b482d`** | Cloudflare Pages β†’ `satquery.pages.dev` |
1232
- | Backend / orchestrator | `SatQuery-Backend` | `main` | **`89d80eaddec5`** | Render β†’ `satquery-backend-m4yv.onrender.com` |
1233
  | Inference | `SatQuery-Inference` | `main` | **`5a0936ace491`** | Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port 8000 |
1234
  | Public umbrella | `SatQuery-AI` | `main` | `3dcabd32da41` | the release home |
1235
  | Monorepo working copy | `C:/Users/anish/satquery-ai` | `master` | `9d57aed` | local only, **no remote**, 334 dirty entries |
 
8
 
9
  > **One-paragraph summary.** SatQuery AI is deployed as **four tiers**: a static browser client on
10
  > **Cloudflare Pages** (`satquery.pages.dev`), a thin stateless **gateway/orchestrator on Render**
11
+ > (`satquery-orchestrator` at `<backend-host>`), a **FastAPI inference service inside
12
  > a GitHub Codespace** (FastAPI on port `8000`), and **Hugging Face** as the project/model-presence tier.
13
  > The gateway does not dial into the Codespace. Instead the Codespace **dials out** to the gateway over a
14
  > long-poll **tunnel** (`POST /tunnel/agent`), because a *forwarded* Codespace port returns **HTTP 302**
 
28
  Cloudflare Pages β€” static frontend satquery.pages.dev
29
  β”‚ HTTPS, JSON, /api/*
30
  β–Ό
31
+ Render β€” orchestrator / API gateway <backend-host>
32
  β”‚ service: satquery-orchestrator
33
  β”‚ outbound long-poll (POST /tunnel/agent) ← direction is INVERTED
34
  β–Ό
 
59
  |---|---|---|---|---|
60
  | Browser | the user's machine | `frontend/` static JS | **No** β€” never | no |
61
  | Static | Cloudflare Pages, `satquery.pages.dev` | HTML/CSS/JS only | **No** | no |
62
+ | Gateway | Render, `satquery-orchestrator`, `<backend-host>` | `deploy/render/main.py` (`SatQuery-Backend` in production) | **Yes** β€” `GITHUB_TOKEN` (and `HF_TOKEN` if the proxy path is used) | no |
63
  | Inference | GitHub Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port `8000` | `app/space_app.py::build_space_app()` via `deploy/codespace/serve.py` | no gateway secrets | ephemeral asset store only |
64
  | Presence | Hugging Face (`hf/`) | project README / model cards | no | no |
65
 
 
732
 
733
  ### 7.1 The measured payload
734
 
735
+ Probed live on 2026-09-25 against `https://<backend-host>/api/health`
736
  (`release/repo/docs/DEPLOYMENT.md` Β§2):
737
 
738
  ```json
 
744
  ```
745
 
746
  Exact command used elsewhere in the project's evidence register:
747
+ `curl --noproxy '*' https://<backend-host>/api/health`
748
  (`docs/FINAL_DELIVERY_REPORT.md` Β§4).
749
 
750
  ### 7.2 Field-by-field
 
1161
  The hub URL is a defaulted variable, so a renamed Render service can be overridden in the Codespace:
1162
 
1163
  ```bash
1164
+ export SATQUERY_HUB_URL="${SATQUERY_HUB_URL:-https://<backend-host>}"
1165
  ```
1166
 
1167
  ### 9.3 The asset-upload environment, and why `/tmp` is correct
 
1229
  | Component | Repository | Branch | Revision | Host |
1230
  |---|---|---|---|---|
1231
  | Frontend | `SatQuery-Frontend` | `main` | **`2d7ae53b482d`** | Cloudflare Pages β†’ `satquery.pages.dev` |
1232
+ | Backend / orchestrator | `SatQuery-Backend` | `main` | **`89d80eaddec5`** | Render β†’ `<backend-host>` |
1233
  | Inference | `SatQuery-Inference` | `main` | **`5a0936ace491`** | Codespace `potential-space-trout-r4ppw969w45j2pvvw`, port 8000 |
1234
  | Public umbrella | `SatQuery-AI` | `main` | `3dcabd32da41` | the release home |
1235
  | Monorepo working copy | `C:/Users/anish/satquery-ai` | `master` | `9d57aed` | local only, **no remote**, 334 dirty entries |