feat(F-049): completed feature

work/artifacts/F-049/architect.md

@@ -0,0 +1,71 @@
+# Architect — F-049
+
+## Goal
+
+Disponer de una operación reproducible del monolito completo en una sola máquina, tanto en desarrollo como en producción local/LAN, sin depender de procesos `nohup` manuales ni PIDs conocidos de antemano.
+
+## Service topology
+
+| Service | Package | Port | LAN binding |
+|---|---|---:|---|
+| Backend API + Swagger | `project/` | 3000 | `0.0.0.0` |
+| Customer frontend | `project/frontend/` | 3003 | `0.0.0.0` |
+| Admin backoffice | `project/apps/admin/` | 3004 | `0.0.0.0` |
+| SEO storefront/ISR | `project/storefront/` | 3005 | `0.0.0.0` |
+| PostgreSQL | Docker | 5432 | infrastructure only |
+| Redis | Docker | 6379 | infrastructure only |
+
+## Operational design
+
+Implement `project/scripts/monolith.sh` as the single lifecycle entrypoint:
+
+```text
+monolith.sh <dev|prod> <start|restart|status|stop|logs|urls>
+```
+
+### Runtime state
+
+- PID files: `project/.runtime/<mode>/<service>.pid`.
+- Logs: `project/.runtime/<mode>/<service>.log`.
+- Runtime files are ignored by Git.
+- A process is considered healthy only when its PID exists and responds on its expected HTTP URL.
+- Stale PID files are removed safely; the script only sends signals to PIDs recorded under the selected mode.
+
+### Development
+
+- Install dependencies package by package.
+- Start Docker PostgreSQL/Redis and wait for readiness.
+- Apply migrations.
+- Run backend with a TypeScript watch runner and each Next package with `next dev`, all bound to `0.0.0.0`.
+- The backend-facing browser variables must use a LAN/browser-reachable API URL rather than `127.0.0.1` when used from another device.
+
+### Production local/LAN
+
+- Install deterministic dependencies (`npm ci`).
+- Apply migrations before process replacement.
+- Build backend and all Next packages.
+- Stop old managed processes gracefully, then start compiled backend and `next start` packages.
+- Validate health/UI HTTP status after startup.
+
+### LAN URL strategy
+
+- Detect the active interface/IP from the default route on macOS, with Linux fallback.
+- Allow override via `LAN_IP`.
+- Export URLs consistently in status/start output.
+- Admin uses its server-side proxy; customer frontends receive `NEXT_PUBLIC_API_URL=http://<LAN_IP>:3000` at build/start.
+
+## Safety
+
+- Do not expose DB/Redis URLs as user-facing links.
+- Production refuses insecure cookies unless explicitly configured for LAN HTTP and documented as local-only.
+- No secrets are printed.
+- Stop/restart must not use broad `pkill`; process ownership comes from PID files.
+- Existing unmanaged listeners are reported as port conflicts, not killed blindly.
+
+## Acceptance evidence
+
+1. `prod restart` builds, migrates, starts all four HTTP services and health-checks them.
+2. `status` shows PID + HTTP health for each service.
+3. LAN URLs respond from the host via the detected LAN address.
+4. HOWTO documents dev/prod start/restart/status/logs/stop and firewall/LAN notes.
+5. Existing quality suites and `verify.sh` remain green.