hamid
146 lines
8.4 KiB
Markdown
146 lines
8.4 KiB
Markdown
# Topology — the runtime dependency graph
|
|
|
|
What talks to what at runtime, what breaks when each hop is down, and which file configures it. This is the
|
|
answer to a deploy question; the deploy *procedure* is [DEPLOY.md](../../DEPLOY.md) and every key is in
|
|
[config-matrix.md](config-matrix.md).
|
|
|
|
> Last verified: 2026-07-30 against commit `d3ec723`, `docker-compose.yml`, `deploy/Caddyfile` and
|
|
> `server/src/API/Baya.Web.Api/Program.cs`.
|
|
|
|
---
|
|
|
|
## Deployed
|
|
|
|
```mermaid
|
|
graph LR
|
|
browser["Browser<br/>balinyaar.ir"]
|
|
|
|
subgraph net["caddy_net (external docker network)"]
|
|
caddy["Caddy<br/><i>pre-existing, not in this repo</i><br/>TLS terminator"]
|
|
web["balinyaar-web:3000<br/>Next.js 16"]
|
|
api["balinyaar-api:8080<br/>ASP.NET Core 10"]
|
|
relay["balinyaar-otp-relay:5010<br/>Node, zero deps"]
|
|
proxy["hysteria-client:8081<br/><i>pre-existing</i>"]
|
|
end
|
|
|
|
sql[("Remote SQL Server<br/>87.107.152.16:1433<br/><b>not containerised</b>")]
|
|
vol[["api-object-storage<br/>docker volume"]]
|
|
tg["api.telegram.org"]
|
|
rails["External rails<br/>PSP · BNPL · Finnotech · Neshan · مودیان<br/><i>all mocked by default</i>"]
|
|
|
|
browser -->|"HTTPS"| caddy
|
|
caddy -->|"HTTP :3000"| web
|
|
browser -->|"HTTPS api.balinyaar.ir<br/><b>every API call</b>"| caddy
|
|
caddy -->|"HTTP :8080<br/>+ X-Forwarded-For"| api
|
|
api -->|"TCP 1433"| sql
|
|
api -->|"HTTP + X-Api-Key"| relay
|
|
api --> vol
|
|
api -.->|"per seam config"| rails
|
|
relay -->|"HTTP CONNECT"| proxy
|
|
proxy --> tg
|
|
|
|
web -.->|"builds absolute URLs only<br/><b>no server-to-server calls</b>"| api
|
|
```
|
|
|
|
**The single most important edge is the dotted one.** The browser calls the API directly at
|
|
`https://api.balinyaar.ir`; the `web` container does **not** proxy or fetch on the browser's behalf. That is
|
|
why `NEXT_PUBLIC_API_URL` must be the **public hostname**, never the container name — a container name is
|
|
unresolvable from a browser. It is also why every `NEXT_PUBLIC_*` change needs an image rebuild: the value
|
|
is compiled into the bundle.
|
|
|
|
## Every edge
|
|
|
|
| # | From → To | Carries | Breaks if down | Configured in |
|
|
| --- | --- | --- | --- | --- |
|
|
| 1 | browser → Caddy | All HTTPS for both hostnames | Everything. Caddy is the only TLS terminator and the only published port | `deploy/Caddyfile` (pasted into the pre-existing Caddy) |
|
|
| 2 | Caddy → `balinyaar-web:3000` | The Next.js app shell, RSC payloads, static assets | The site does not load. **The API keeps working** — they are independent hostnames | `Caddyfile` · `docker-compose.yml` |
|
|
| 3 | browser → Caddy → `balinyaar-api:8080` | Every `/api/v1/*` call, bearer-authenticated | The site loads and every screen shows its error state. No data, no login | `NEXT_PUBLIC_API_URL` (build-time) · `Cors:AllowedOrigins` |
|
|
| 4 | Caddy → API, `X-Forwarded-For` | The real client IP | The rate limiter partitions every request onto **Caddy's** IP, so one noisy client 429s everyone | `ForwardedHeaders:KnownNetworks` — the docker bridge ranges |
|
|
| 5 | API → remote SQL Server | All application data + the Serilog sink | **Total outage.** `/healthz/ready` fails and the API will not start | `ConnectionStrings:SqlServer` / `:logDb` |
|
|
| 6 | API → `balinyaar-otp-relay:5010` | OTP codes, `X-Api-Key` authenticated | **Nobody can log in.** Every other authenticated screen keeps working for existing sessions | `Seams__Sms__Telegram__BaseUrl` (compose) · `Seams:Sms:Telegram:ApiKey` |
|
|
| 7 | relay → `hysteria-client:8081` → Telegram | The code delivery itself | Same as 6 — codes are generated but never arrive. Fails **at relay boot** with a clear message, not silently per-OTP | `TELEGRAM_PROXY_URL` |
|
|
| 8 | API → `api-object-storage` volume | Verification documents, avatars | Uploads fail; `/healthz/ready` fails (it does a real write probe). **Without the volume, existing documents vanish on the next `up --build`** | `Seams__ObjectStorage__RootPath` + the named volume |
|
|
| 9 | API → external rails | Payments, BNPL, KYC, geocoding, e-invoicing | **Nothing, by default** — every rail is `mock`. Real behaviour begins the moment a `Provider` selector changes | `Seams:<rail>:Provider` — see [config-matrix.md](config-matrix.md#the-seam-selectors) |
|
|
| 10 | PSP / BNPL / transferor → API webhooks | Payment capture, BNPL settlement, payout reconciliation | Payments are taken but **bookings are never confirmed** — the webhook is what creates the booking | `webhook` rate-limit policy, anonymous routes, per-provider signing secrets |
|
|
|
|
## Ports
|
|
|
|
| Port | Where it applies | Note |
|
|
| --- | --- | --- |
|
|
| `443` | The host | Caddy. **The only published port on the machine** |
|
|
| `3000` | `caddy_net` only | Next.js. Not published |
|
|
| `8080` | `caddy_net` only | The API **in-container** |
|
|
| `5002` | A developer laptop only | The local `launchSettings.json` port — **plain HTTP**, and nothing in the deployment uses it |
|
|
| `5010` | `caddy_net` only | The OTP relay |
|
|
| `1433` | Outbound to `87.107.152.16` | Remote SQL Server |
|
|
|
|
> **5002 vs 8080 catches people out.** Most prose in this repo says 5002 because that is the local port.
|
|
> The container binds 8080 (the ASP.NET default in a container) and the Caddyfile points there.
|
|
|
|
## Startup order
|
|
|
|
`depends_on: [otp-relay]` puts the relay before the API, but that only orders *container start*, not
|
|
readiness. What actually gates the API's boot:
|
|
|
|
1. **`StartupSecretsGuard`** — refuses to start on a missing or placeholder secret, before any service reads
|
|
config.
|
|
2. **A reachable SQL Server** — required to start, full stop.
|
|
3. **In Development** (which is what the deployment runs): apply migrations, then seed default users,
|
|
payment gateways, the demo world and the demo lifecycle. All idempotent — a re-boot logs
|
|
`Demo world already seeded — no-op.` **First boot takes ~40 s** against the remote DB.
|
|
4. **When deployed as a non-Development environment**: DDL is a separate one-shot
|
|
(`dotnet Baya.Web.Api.dll migrate`); boot only *checks* the schema is current and fails fast on a pending
|
|
migration, then seeds roles.
|
|
|
|
The relay refuses to start without `API_KEY` (min 16 chars) or with an unreachable proxy — both fail loudly
|
|
at boot rather than per-request.
|
|
|
|
## Request pipeline inside the API
|
|
|
|
Order matters, and two placements are deliberate:
|
|
|
|
```
|
|
UseForwardedHeaders ← first, so the resolved client IP is in place before anything reads it
|
|
UseSwaggerAndUi
|
|
UseRouting
|
|
UseCors ← after routing, BEFORE the rate limiter and auth, so a pre-flight OPTIONS
|
|
UseRateLimiter is answered rather than rejected as 429 or 401
|
|
UseAuthentication
|
|
UseAuthorization
|
|
MapControllers
|
|
UseMetrics · UseHealthChecks
|
|
ConfigureGrpcPipeline
|
|
```
|
|
|
|
## What is not in the graph
|
|
|
|
| | Why |
|
|
| --- | --- |
|
|
| A database container | The DB is remote and pre-provisioned. `RUNBOOK.md`'s local-SQL-in-Docker path describes a **different world** — an unseeded one (contradiction **C-5**) |
|
|
| Redis | `ICacheService` / `IDistributedLock` are single-process today. When a multi-instance deployment needs a real one, a `redis` readiness check gets added alongside it |
|
|
| A job runner | The weekly payout batch is generated by an **in-process** `IRecurringJob` scheduler. No external cron, no queue |
|
|
| A message broker | Nothing is asynchronous across a process boundary |
|
|
| An OTLP collector | `OpenTelemetry:Otlp:Endpoint` is unset, so nothing is exported. Prometheus scrapes `/metrics` directly |
|
|
| A second API instance | Single instance. Multi-instance needs the distributed lock to become real first |
|
|
|
|
## Local development
|
|
|
|
Same code, a different graph — no Caddy, no containers, and the **same remote database**:
|
|
|
|
```
|
|
localhost:3000 (npm run dev) ──▸ localhost:5002 (dotnet run, plain HTTP)
|
|
│
|
|
├──▸ 87.107.152.16:1433 (the same remote DB)
|
|
└──▸ 127.0.0.1:5010 (the relay, if you run it)
|
|
```
|
|
|
|
Three things to know before the first run:
|
|
|
|
- **The API is plain HTTP locally.** `dotnet dev-certs https --trust` is not needed and there is no
|
|
certificate to trust (contradiction **C-4**).
|
|
- **You share the deployment's database.** Booting in Development migrates and seeds against it. The
|
|
seeders are idempotent, but you and the demo site are looking at the same rows.
|
|
- **If you run the relay locally**, copy `Seams:Sms:Telegram:ApiKey` from `appsettings.Development.json`
|
|
into your own `telegram-otp-bot/.env`. The value in `.env.example` is published and
|
|
`TelegramSmsSender` deliberately rejects it.
|