# 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.