rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db33706d2d9e10826454071b6cd009a260015def
mercadodevida/work/artifacts/F-049/architect.md
chattie e86034a62c feat(F-049): completed feature
2026-08-19 07:34:15 +02:00

2.9 KiB
Raw Blame History

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:

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.