72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
# 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.
|