# Inventário de serviços executáveis do monorepo + subida local nativa (sem Docker)

Data: 2026-07-10. Escopo: todos os serviços executáveis de `/Users/luizpenha/monetarie` (Core, PIX, SPB, NPC, STA, CLST, backoffice, docs, mobile), com tecnologia, comando de boot local nativo, porta default, banco, dependências de infra e variáveis de ambiente essenciais. Acompanha os scripts novos `scripts/dev_up_all.sh` e `scripts/dev_down_all.sh` (seção 8) e o fluxo para dev novo (seção 10).

Regra de ouro deste inventário: ambiente local roda com simulador LIGADO e BACEN/HSM/MQ DESLIGADOS. Nada aqui toca BACEN real, HSM RTM ou IBM MQ.

Nota de escopo: `core/docs-site` (VitePress, pacote `@monetarie/docs`) existe e tem `dev: vitepress dev`, mas está sendo trabalhado por outra sessão e ficou fora deste inventário de subida.

## 1. Infra local compartilhada

| Componente | Porta local | Quem usa | Evidência |
|---|---|---|---|
| PostgreSQL | 5432 nativo (os `dev.exs` defaultam 15432, porta do docker compose; exportar `DB_PORT=5432`) | todos os backends Elixir | `core/backend/config/dev.exs:24-28`, `pix/backend/config/dev.exs:5-9`, `spb/services/bacen_gateway/config/config.exs:14-20` |
| NATS JetStream | 4222 (monitor 8222) | core, pix (opt-in), spb, npc, sta, clst | `core/backend/config/dev.exs:95-97`, `docker-compose.yml:28-34` (referência de versão 2.10, `-js`) |
| TigerBeetle 0.17.3 | 3001 | somente core | `core/backend/config/dev.exs:10-14` (`TIGERBEETLE_ADDRESSES` default `127.0.0.1:3001`); regra #8 do `CLAUDE.md` raiz fixa a versão 0.17.3 |
| Redis | 6379 | core (boot cedo) e pix (pool Redix obrigatório no boot) | `core/backend/config/config.exs:336`, `pix/backend/apps/shared/lib/shared/redis/connection.ex:149-150` |

Credenciais default dos configs de dev (iguais em todos os backends): usuário `monetarie`, senha `MonetarieDB@2026`, host `localhost`. Cada backend usa seu próprio banco via `DB_NAME` com default por sistema, então `DB_NAME` NUNCA deve ser exportado globalmente.

Atenção: o SPB lê a senha de `DB_PASSWORD` (`spb/services/bacen_gateway/config/config.exs:14-20`), enquanto core/pix/npc/sta/clst leem `DB_PASS`. O `dev_up_all.sh` exporta as duas.

## 2. Backends (APIs)

| Serviço (nome ECS) | Caminho | Tecnologia | Boot local | Porta dev | Banco (Repo Ecto) | Deps de infra |
|---|---|---|---|---|---|---|
| core-api | `core/backend` | Elixir/Phoenix 1.8, app único `:monetarie` | `mix phx.server` | 4000 (`config/dev.exs:56`) | `mon_core` (`Monetarie.Infra.Repo.Base` + pools `Batch`/`Reader`, `config/dev.exs:26-52`) | Postgres, TigerBeetle 3001, NATS 4222, Redis 6379 |
| pix-api | `pix/backend` | Elixir/Phoenix, UMBRELLA (`mix.exs:6` `apps_path: "apps"`) | `mix phx.server` (sobe os 3 endpoints) | dict 4001, spi 4002, settlement 4003 (`config/dev.exs:59,68,76`) | `mon_pix` (4 repos no mesmo banco: `Shared.Repo`, `DictService.Repo`, `SpiService.Repo`, `SettlementService.Repo`, `config/dev.exs:4-39`) | Postgres, Redis (obrigatório no boot), NATS (só com `NATS_ENABLED=true`) |
| spb-api | `spb/services/bacen_gateway` | Elixir/Phoenix, app único `:bacen_gateway` (`mix.exs:6`) | `mix phx.server` | 4010 (`config/dev.exs:5`) | `mon_spb` (`BacenGateway.Repo`, `config.exs:14-20,35`) | Postgres (única dependência dura, Repo é o 1º filho em `application.ex:54`); NATS e Redis reconectam em background e não bloqueiam o boot |
| npc-api | `npc/backend` | Elixir/Phoenix, app único `:monetarie_npc` (`mix.exs:6`) | `mix phx.server` | 4020 (`config/dev.exs:23`) | `mon_npc` (`MonetarieNpc.Repo`, `config/dev.exs:4-12`) | Postgres, NATS |
| sta-api | `sta/backend` | Elixir/Phoenix, app único `:sta_connector` (`mix.exs:8`) | `mix phx.server` | 4030 (`config/dev.exs:19`) | `mon_sta` (`StaConnector.Repo`, `config/dev.exs:4-12`) | Postgres, NATS |
| clst-api | `clst/` (app na raiz) | Elixir/Phoenix, app único `:monetarie_clst` (`mix.exs:6`) | `mix phx.server` | 4004 (`config/dev.exs:10`) | `mon_clst` (`MonetarieClst.Repo`, `config/config.exs:10-15`) | Postgres, NATS, core-api em `http://localhost:4000` (`config/config.exs:33-35`) |

Aliases de banco por backend (o que o `ecto.setup` faz):

| Backend | `mix ecto.setup` | Seeds | Evidência |
|---|---|---|---|
| core-api | create + migrate + seeds | `priv/repo/seeds.exs` (orquestra `priv/repo/seeds/*`, ~59 arquivos incl. `tigerbeetle.exs`) | `core/backend/mix.exs:107` |
| pix-api | create + migrate + seeds | `apps/shared/priv/repo/seeds.exs` (participantes, usuários, XSDs, COSIF) | `pix/backend/mix.exs:25-32` |
| spb-api | create + migrate (SEM seeds) | ~40 seeds numerados em `priv/repo/seeds/`, manuais via `spb/services/bacen_gateway/run-seeds.sh` (3 arquivos sensíveis estão no gitignore) | `spb/services/bacen_gateway/mix.exs:68-74` |
| npc-api | create + migrate (SEM seeds) | `priv/repo/seeds.exs` existe, rodar manual com `mix run priv/repo/seeds.exs` | `npc/backend/mix.exs:79-86` |
| sta-api | create + migrate + seeds | `priv/repo/seeds.exs` | `sta/backend/mix.exs:87-92` |
| clst-api | create + migrate (SEM seeds) | `priv/repo/seeds.exs` existe, rodar manual | `clst/mix.exs:66-73` |

## 3. Frontends (UIs)

| Serviço (nome ECS) | Caminho | Nome no package.json | Tecnologia | Boot local | Porta dev | API |
|---|---|---|---|---|---|---|
| core-admin-ui | `core/apps/admin` | `@monetarie/admin` | Vue 3 + Vite + PrimeVue | `pnpm --filter @monetarie/admin dev` (na raiz `core/`) | 5174 (`vite.config.ts:21` bloco server) | proxy `/api` para `http://localhost:4000` (`vite.config.ts:22-26`); `VITE_API_URL` default `/api` (`src/lib/api.ts:9`) |
| core-banking-ui | `core/apps/banking` | `@monetarie/banking` | Vue 3 + Vite + PrimeVue + Tailwind 4 | `pnpm --filter @monetarie/banking dev` | 3000 (`vite.config.ts:18`) | proxy `/api` para 4000 (`vite.config.ts:20-24`) |
| core-merchant-ui | `core/apps/merchant` | `@monetarie/merchant-portal` | Vue 3 + Vite + PrimeVue | `pnpm --filter @monetarie/merchant-portal dev` | 3002 (`vite.config.ts:14`) | proxy `/api` para `VITE_API_URL` ou 4000 (`vite.config.ts:15-19`) |
| pix-admin-ui | `pix/frontend/admin` | `vue_admin_portal` | Vue 3 + Vite 7 + Pinia + Tailwind 4 | `npm run dev` | 5175 (`vite.config.ts`, `server.port`) | proxy `/api` e `/socket` (ws) para `http://localhost:4003` (settlement gateway); `VITE_API_BASE_URL` default vazio (`src/services/api.ts:7`) |
| spb-admin-ui | `spb/frontend-vue` | `monetarie-spb-frontend` | Vue 3 + Vite 7 + Vuetify 3 + Pinia + i18n | `npm run dev` | 5173 (`vite.config.ts`, `server.port`) | proxy `/api` e `/socket` para `http://localhost:4010`; `VITE_API_URL` default `/api` (`src/services/api.ts:5`) |
| npc-frontend | `npc/frontend` | `frontend` | Vue 3.5 + Vite 7 + Tailwind 4 | `npm run dev` | 5177 (`vite.config.ts:14`) | SEM proxy no Vite; `VITE_API_URL` default `/api` (`src/services/api.ts:7`); para local exportar `VITE_API_URL=http://localhost:4020/api` (o `dev_up_all.sh` já faz) |
| sta-frontend | `sta/frontend` | `sta-connector-admin` | Vue 3.5 + Vite 7 + Tailwind | `npm run dev` | 5178 (`vite.config.ts:13`) | proxy `/api` e `/socket` para `http://localhost:4030` (`vite.config.ts:13-38`) |
| sta-admin-portal | `sta/admin-portal` | `monetarie-sta-admin-portal` | React 18 + Vite 5 + react-query | `npm run dev` | 5179 (`vite.config.ts:14`) | proxy `/api` e `/health` para 4030 (`vite.config.ts:14-27`) |
| backoffice | `backoffice/` | `monetarie-backoffice` | Vue 3 + Vuetify 3 + Vite 7 | `npm run dev` | 5176 (`vite.config.ts:17`) | SEM proxy no Vite; `VITE_API_URL` default `/api` (`src/shared/services/api.ts:1`); em deploy usa nginx `/api/v1` para o Core; para local exportar `VITE_API_URL=http://localhost:4000/api/v1` (o `dev_up_all.sh` já faz) |

Dependência de build dos frontends do core: o pacote `@monetarie/shared` (`core/packages/shared`, lib tsup, não é serviço) precisa ser buildado antes dos apps Vue: `pnpm --filter @monetarie/shared build`. Workspace pnpm em `core/pnpm-workspace.yaml` (`apps/*`, `packages/*`, `docs-site`); atalhos na raiz `core/package.json` (`dev:admin`, `dev:banking`, `dev:merchant`).

## 4. Simuladores

| Serviço | Caminho | Tecnologia | Boot local | Porta dev | Observações |
|---|---|---|---|---|---|
| Simulador BACEN do PIX | embutido no pix-api (`Shared.Bacen.Simulator`) | GenServer Elixir | sobe junto com o backend quando `SIMULATOR_ENABLED=true` | usa o 4003 (rotas `/api/v1/simulator`) | `pix/backend/apps/shared/lib/shared/application.ex:19,142` |
| pix simulator-frontend | `pix/simulator-frontend` | Vue 3 + Vite 7 | `npm run dev` | 5182 (`vite.config.ts`, `server.port`) | proxy `/api/v1/simulator` para `http://localhost:4003`; nome `monetarie-pix-simulator` |
| spb-simulator | `spb/simulator` | Elixir/Phoenix, app único `:simulator` | `mix phx.server` | 4001 (`config/dev.exs:8`) | SEM banco: `Simulator.Persistence.StateStore` usa Postgres com fallback ETS (`lib/simulator/persistence/state_store.ex:3-7`), roda sem Postgres; simula 979 tipos de mensagem |
| spb simulator-frontend | `spb/simulator-frontend` | Vue 3 + Vite | QUEBRADO | 5181 (`vite.config.ts`) | NÃO tem `package.json` no repo (só `package-lock.json`), e o proxy aponta para `:4100` enquanto o simulador roda em `:4001`; precisa de restauração antes de ser executável |
| npc simulator-frontend | `npc/simulator-frontend` | Vue 3.5 + Vite 7 | `npm run dev` | 5180 (`vite.config.ts:7`) | nome `monetarie-npc-simulator`; espera um backend de simulador em `VITE_SIMULATOR_BACKEND_URL` (`.env.example`, default `http://localhost:4300`) que não existe no repo |

COLISÃO DE PORTA: o spb-simulator fixa 4001 em dev (`spb/simulator/config/dev.exs:8`) e o `PORT` só é lido em prod (`spb/simulator/config/runtime.exs:9,18`). O dict_service do PIX também usa 4001. O `dev_up_all.sh` só sobe o spb-simulator se a 4001 estiver livre e avisa quando pula.

## 5. Sidecars e demais executáveis

| Serviço | Caminho | Tecnologia | Como roda | Porta | Necessário em dev local? |
|---|---|---|---|---|---|
| Sidecar MQ do SPB | `spb/services/bacen_gateway_mq_sidecar` | Java 17 + Maven (IBM MQ allclient/JMS), `artifactId spb-mq-sidecar`, mainClass `com.monetarie.bacen.Sidecar` (`pom.xml:74`) | `mvn package` e `java -jar target/sidecar.jar` (`entrypoint.sh:25`) | 9080 (o bacen_gateway espera `IBM_MQ_SIDECAR_URL=http://localhost:9080`, `runtime.exs:127`) | NÃO: só com `IBM_MQ_ENABLED=true` + MQ real via RTM; em dev `mq_enabled: false` (`config.exs:50`) |
| Sidecar mTLS do PIX | `pix/services/bacen_mtls_sidecar` | Go 1.25 (`go.mod`), net/http puro | `go build -o sidecar . && ./sidecar` | health 9100, upstreams 9101 a 9105 (`main.go:540-542,621-622`) | NÃO: só para BACEN real com HSM (`BACEN_ENABLED=true` + `RTM_HSM_ENABLED=true`); a chave PIC vive no HSM |
| docs-portal | `docs-portal/` | site estático (nginx 1.27, `Dockerfile:1,20`) | sem dev server nativo; abrir `public/index.html` ou servir com nginx local | 8080 (container) | opcional |
| mobile | `mobile/` | Flutter, app `monetarie_mobile` (`pubspec.yaml:1`) | `flutter run` (flavors via `build_flavor.sh` e `flavors/monetarie.env`) | n/a | opcional |
| benchmark | `benchmark/` | projeto Mix `:bench` (`mix.exs:12`) | `mix run -e '...'` (harness de perf do money path, com guarda anti-prod) | n/a | ferramenta, não serviço |
| core/e2e | `core/e2e` | Playwright (testes) | n/a | n/a | não é serviço |

NÃO SUBIR: os 9 microserviços legados "SPB Cabin" em `spb/services/` (`api_gateway`, `cash_service`, `forex_service`, `securities_service`, `settlement_service`, `transaction_service`, `user_management`, `extract_service`, `message_processor`). São scaffolding de uma arquitetura antiga, não deployados, e sete deles colidem na porta 4000 em dev. O backend real do SPB é só o `bacen_gateway`. O `services/Makefile` e o `services/quickstart.sh` que os orquestram estão estanques (referenciam `auth_service` inexistente e exigem Docker).

## 6. Estrutura dos backends Elixir

### core/backend (`:monetarie`)
Aplicação Mix ÚNICA (não umbrella): `app: :monetarie` em `core/backend/mix.exs:6`, `mod: {Monetarie.Application, []}` em `mix.exs:19`. Domínio em `lib/monetarie`, web em `lib/monetarie_web` (endpoint `MonetarieWeb.Endpoint`, `config/dev.exs:55`). Supervisão: Redis sobe cedo (`lib/monetarie/application.ex:65`), depois Repos (Base/Batch/Reader), pool TigerBeetle (`tigerbeetlex` vendorado em `core/backend/vendor/tigerbeetlex`), conexão NATS, Oban (inline em dev, `config/dev.exs:74`) e o Endpoint (`application.ex:184`). Sem bloco `releases` no mix.exs, então o release usa o nome default `monetarie` (`bin/monetarie`, consistente com o deploy). `ecto_repos` só migra o Base (`config/config.exs:6`).

### pix/backend (umbrella, release `:monetarie_pix`)
Único umbrella do monorepo: `apps_path: "apps"` (`pix/backend/mix.exs:6`). Quatro apps:

| App | Endpoint | Porta dev | Papel |
|---|---|---|---|
| `:shared` | nenhum | n/a | schemas, cliente BACEN, Redis, NATS, crypto, simulador |
| `:dict_service` | `DictServiceWeb.Endpoint` | 4001 | DICT |
| `:spi_service` | `SpiServiceWeb.Endpoint` | 4002 | SPI |
| `:settlement_service` | `SettlementServiceWeb.Endpoint` | 4003 | gateway de API + WebSocket `/socket` (é para cá que o pix-admin-ui aponta) |

`Shared.Application` valida no boot que ao menos uma entre `BACEN_ENABLED` e `SIMULATOR_ENABLED` esteja `true`, senão levanta erro (`apps/shared/lib/shared/application.ex:19,25-36`). Com `SIMULATOR_ENABLED=true` sobe o GenServer `Shared.Bacen.Simulator` (`application.ex:142`). Workers NATS só sobem com `NATS_ENABLED=true` (`application.ex:18,155`). Release `:monetarie_pix` com os 4 apps `:permanent` (`mix.exs:34-49`). Migração em release: `bin/monetarie_pix eval "Shared.Release.migrate()"`. Não usa TigerBeetle.

### spb/services/bacen_gateway (`:bacen_gateway`)
Monólito Phoenix (1997 arquivos `.ex`, 73 controllers), `mod: {BacenGateway.Application, []}` (`mix.exs:19`). O Repo é o primeiro filho do supervisor (`lib/bacen_gateway/application.ex:54`, dependência dura); NATS via `Gnat.ConnectionSupervisor` (`application.ex:66`) e Redis via `BacenGateway.Cache`/Redix (`lib/bacen_gateway/cache.ex:30-42`) reconectam em background sem derrubar o boot. Ponto crítico de configuração: o `config/runtime.exs` INTEIRO está sob `if config_env() == :prod` (`runtime.exs:3`), então em dev valem apenas os defaults do `config.exs`: MQ desligado (`mq_enabled: false`, `config.exs:50`), Liquidante desligado (`config.exs:110`), DDA ligado (`config.exs:128`), `outbox_strict_mode: true` (`dev.exs:37`). Sem bloco `releases`.

### npc/backend (`:monetarie_npc`), sta/backend (`:sta_connector`), clst (`:monetarie_clst`)
Apps Phoenix únicos, padrão `mix phx.server`. Releases nomeados: `monetarie_npc` (`npc/backend/mix.exs:14-19`), `sta_connector` (`sta/backend/mix.exs:102-109`), `monetarie_clst` (`clst/mix.exs:13-18`). Atenção no NPC: `PORT` só é lido em prod (`npc/backend/config/runtime.exs:24-27`), em dev a porta é fixa 4020; o `npc/start_all.sh` legado passa `PORT=4000` acreditando mudar a porta, e ainda depende de um worktree `.worktrees/nuclea-simulator` inexistente (`start_all.sh:19,28-31`), portanto está desatualizado. No STA, o dev roda com `test_mode: true` (workers em simulação, `sta/backend/config/dev.exs:81-86`) e poller desligado (`dev.exs:76-79`). O CLST consome a API do Core em `http://localhost:4000` (`clst/config/config.exs:33-35`).

### spb/simulator (`:simulator`)
Phoenix com assets próprios via esbuild, 106 arquivos `.ex`. Sem Repo Ecto: persistência via `Simulator.Persistence.StateStore` com fallback ETS (`lib/simulator/persistence/state_store.ex:3-7`). `MQ_POLLING_ENABLED` default `false` (`config/config.exs:41-46`).

## 7. Variáveis de ambiente essenciais para dev local

O `dev_up_all.sh` exporta exatamente este conjunto (ambiente 100% local):

| Variável | Valor local | Quem lê | Evidência |
|---|---|---|---|
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASS` | `localhost` / `5432` / `monetarie` / senha do dev.exs | todos os backends | `core/backend/config/dev.exs:27-30` e equivalentes |
| `DB_PASSWORD` | igual a `DB_PASS` | só spb-api | `spb/services/bacen_gateway/config/config.exs:14-20` |
| `DB_NAME` | NÃO exportar global (default por sistema) | todos | `mon_core`/`mon_pix`/`mon_spb`/`mon_npc`/`mon_sta`/`mon_clst` |
| `NATS_HOST` / `NATS_PORT` | `localhost` / `4222` | core, pix, npc, sta, clst | `core/backend/config/dev.exs:95-97` |
| `TIGERBEETLE_ADDRESSES` | `127.0.0.1:3001` | core | `core/backend/config/dev.exs:14` |
| `SIMULATOR_ENABLED` | `true` (OBRIGATÓRIO para o pix subir) | pix | `pix/backend/apps/shared/lib/shared/application.ex:19,25-36` |
| `NATS_ENABLED` | `true` (liga workers NATS do pix) | pix | `application.ex:18` |
| `BACEN_ENABLED` | `false` | pix (e checagens espalhadas) | `pix/backend/config/runtime.exs:346` |
| `RTM_HSM_ENABLED` | `false` | pix e spb | `pix/backend/config/runtime.exs:90`, `spb .../runtime.exs:99` (prod) |
| `IBM_MQ_ENABLED` | `false` | spb (em dev já é `false` por default no `config.exs:50`) | `spb .../runtime.exs:121` |
| `DICT_EXTERNAL_MODE` | `local` | pix | `pix/backend/config/runtime.exs:109-124` |
| `NPC_SIMULATOR_ENABLED` | `true` | npc | `npc/backend/config/runtime.exs:56-71` |
| `STA_BASE_URL` | `http://localhost:4030` | core (integração CADOC/STA; default de dev aponta para DNS docker) | `core/backend/config/dev.exs:149-156` |

Flags que NUNCA devem ser ligadas localmente: `TWO_PHASE_PIX_IN` (proibida por decisão canônica, `CLAUDE.md` raiz), `BACEN_ENABLED`, `RTM_HSM_ENABLED`, `IBM_MQ_ENABLED`.

## 8. Scripts de subida e derrubada

Novos (validados com `bash -n`, sem Docker):

- `scripts/dev_up_all.sh [all|infra|core|pix|spb|npc|sta|clst|backoffice]`
  - Preflight fail-fast: elixir/mix, node/npm, pnpm (só core), psql, Postgres aceitando conexão e autenticando o role, nats-server, Redis respondendo PONG (core/pix), binário TigerBeetle com checagem de versão 0.17.3 (só core/infra). Cada falha imprime o comando brew/asdf ou o download correto.
  - Infra: `nats-server -js -sd ./.data/nats -p 4222` e TigerBeetle 0.17.3 com `format` (uma vez) + `start --addresses=3001 --development ./.data/tigerbeetle/0_0.tigerbeetle`, ambos em background com log próprio.
  - Bancos: por backend, `mix deps.get` e depois `mix ecto.setup` na primeira vez (quando o banco não existe; roda seeds onde o alias inclui) ou `mix ecto.migrate` nas seguintes.
  - Serviços: cada backend e frontend sobe em background com log em `./.data/logs/<serviço>.log` e PID file em `./.data/pids/<serviço>.pid`; espera de porta com timeout; serviços já vivos são pulados (idempotente).
  - Proteções: só sobe o spb-simulator se a 4001 estiver livre (colisão com o dict do PIX); não sobe o spb/simulator-frontend (quebrado, seção 4); nunca liga BACEN/HSM/MQ.
- `scripts/dev_down_all.sh [all|infra|core|pix|spb|npc|sta|clst|backoffice]`: mata pela árvore de processos de cada PID file (TERM, espera, KILL), derrubando apps antes da infra.

O diretório `./.data/` (dados do TigerBeetle, store do JetStream, logs e PIDs) foi adicionado ao `.gitignore`.

Scripts pré-existentes no repo (citados e aproveitados como referência):

- `core/backend/tigerbeetle/{config.sh,run.sh,start.sh}`: format/start local do TigerBeetle, mas na porta 10000, enquanto o `dev.exs` do core espera 3001; o script novo usa 3001 para casar com o config.
- `spb/services/bacen_gateway/run-seeds.sh` e `spb/scripts/deploy_seeds.sh`: carga manual dos seeds do SPB.
- `npc/start_all.sh` e `npc/backend/start_backend.sh`: parcialmente desatualizados (worktree inexistente, `PORT` ignorado em dev).
- `spb/services/quickstart.sh` e `spb/services/Makefile`: exigem Docker e orquestram a arquitetura legada, não usar.
- `core/package.json`: atalhos pnpm `dev`, `dev:admin`, `dev:banking`, `dev:merchant`.
- `scripts/deploy_hml_arm64.sh` e demais em `scripts/`: deploy AWS e relatórios, nada de subida local.

## 9. O que está instalado nesta máquina (verificado em 2026-07-10)

| Dependência | Estado | Detalhe |
|---|---|---|
| Elixir / Erlang | OK | Elixir 1.19.5, OTP 28 (Homebrew); os projetos pedem `~> 1.17`, satisfeito; asdf presente mas sem versões gerenciadas por ele |
| Node / npm / pnpm | OK | Node v24.1.0, npm 11.3.0, pnpm 9.15.0 (o workspace do core pede pnpm 9.15.0), yarn 1.22.22 |
| PostgreSQL | OK, RODANDO | PostgreSQL 16.11 via `brew services` (`postgresql@16`) na 5432; roles `postgres` e `monetarie` existem e autenticam; psql cliente 18.1 (libpq) |
| Redis | OK, RODANDO | Redis 8.8.0 via `brew services` na 6379 |
| nats-server | FALTA | instalar com `brew install nats-server` |
| tigerbeetle | FALTA | baixar a release 0.17.3 (`tigerbeetle-universal-macos.zip` do GitHub) para `./.data/bin/`; NÃO usar `brew install tigerbeetle` (instalaria versão mais nova, e a regra do repo exige 0.17.3) |
| Java | OK | OpenJDK 17 (suficiente para o sidecar MQ, que não é usado localmente) |
| Go | OK | go 1.25.6 (sidecar mTLS do PIX, não usado localmente) |
| Flutter | OK | presente (mobile) |

Ressalva honesta: a máquina tem OTP 28 e os locks dos projetos foram gerados com OTP 27; se alguma dep nativa (por exemplo o `tigerbeetlex` vendorado) falhar ao compilar, a saída é instalar Elixir 1.17 + OTP 27 via asdf e apontar o projeto para ela.

## 10. Como usar (fluxo para um dev novo)

1. Pré-requisitos de máquina (uma vez):
   - `brew install elixir node pnpm postgresql@16 redis nats-server`
   - `brew services start postgresql@16 && brew services start redis`
   - Crie o role do banco se não existir: `psql -h localhost -U postgres -c "CREATE ROLE monetarie LOGIN SUPERUSER PASSWORD '<senha default do dev.exs>'"` (a senha default está em `core/backend/config/dev.exs:30`).
   - TigerBeetle 0.17.3: baixe `tigerbeetle-universal-macos.zip` da release 0.17.3 no GitHub do TigerBeetle e descompacte em `./.data/bin/` (o preflight do script imprime o comando exato se faltar).
2. Suba tudo: `./scripts/dev_up_all.sh` (primeira execução compila os backends e roda migrations/seeds, demora vários minutos; acompanhe em `./.data/logs/*-setup.log`).
3. Ou suba um sistema só: `./scripts/dev_up_all.sh pix` (a infra necessária sobe junto).
4. Acesse:
   - Core: API `http://localhost:4000`, admin `http://localhost:5174`, internet banking `http://localhost:3000`, merchant `http://localhost:3002`
   - PIX: gateway `http://localhost:4003` (dict 4001, spi 4002), admin `http://localhost:5175`, simulador UI `http://localhost:5182`
   - SPB: API `http://localhost:4010`, admin `http://localhost:5173`, simulador `http://localhost:4001` (quando a porta está livre)
   - NPC `http://localhost:4020` + UI `http://localhost:5177`; STA `http://localhost:4030` + UIs `5178`/`5179`; CLST `http://localhost:4004`; backoffice `http://localhost:5176`
5. Credenciais de dev: as defaults ficam nos configs (`core/backend/config/dev.exs:84-86` para o admin do core, `sta/backend/config/dev.exs:61` para o STA); os seeds do pix criam os usuários administrativos da cabine.
6. Logs e ciclo de vida: `tail -f .data/logs/<serviço>.log`; derrube com `./scripts/dev_down_all.sh` (ou `./scripts/dev_down_all.sh pix` para um sistema; `infra` derruba NATS e TigerBeetle).
7. Seeds manuais quando precisar: SPB `cd spb/services/bacen_gateway && ./run-seeds.sh`; NPC `cd npc/backend && mix run priv/repo/seeds.exs`; CLST `cd clst && mix run priv/repo/seeds.exs`.
8. Nunca ligue `BACEN_ENABLED`, `RTM_HSM_ENABLED`, `IBM_MQ_ENABLED` ou `TWO_PHASE_PIX_IN` localmente. O ambiente local é 100% simulado por design.