From a115b0d4cbac2736c3649baf4f6903d55d247c9e Mon Sep 17 00:00:00 2001
From: Bruno <brunodaniel.elias@gmail.com>
Date: Fri, 10 Jul 2026 09:22:21 -0300
Subject: [PATCH] chore(dev): add User API lane to the local dev stack
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scripts/dev.sh gains an optional User API lane (port 4003) mirroring the
Address Enrichment one — started via `railway run` when the service is
available (it needs the Railway dev Postgres), exporting USER_API_URL for
the dashboard /api/user proxy, and skipped otherwise. Adds the `pnpm
user-api` root alias and documents the port in the local-dev-stack skill.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/user-api-dev-stack-lane.md   |  4 ++++
 .claude/skills/local-dev-stack/SKILL.md |  1 +
 package.json                            |  1 +
 scripts/dev.sh                          | 25 ++++++++++++++++++++++++-
 4 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/user-api-dev-stack-lane.md

diff --git a/.changeset/user-api-dev-stack-lane.md b/.changeset/user-api-dev-stack-lane.md
new file mode 100644
index 000000000..ceca9851f
--- /dev/null
+++ b/.changeset/user-api-dev-stack-lane.md
@@ -0,0 +1,4 @@
+---
+---
+
+chore: add a local dev-stack lane for the User API (`scripts/dev.sh`) + `pnpm user-api` root alias. Optional, mirroring Address Enrichment — runs via `railway run` when the service is available and exports `USER_API_URL` for the dashboard `/api/user` proxy; skipped otherwise so existing flows are unaffected.
diff --git a/.claude/skills/local-dev-stack/SKILL.md b/.claude/skills/local-dev-stack/SKILL.md
index 645746442..96484879a 100644
--- a/.claude/skills/local-dev-stack/SKILL.md
+++ b/.claude/skills/local-dev-stack/SKILL.md
@@ -46,6 +46,7 @@ the first.
 | Dashboard          | 3000  | http://localhost:3000  | always                              |
 | Address Enrichment | 3001  | http://localhost:3001  | optional, skipped if no Railway svc |
 | Relayer (ENS)      | 3002  | http://localhost:3002  | ENS only                            |
+| User API           | 4003  | http://localhost:4003  | optional, skipped if no Railway svc |
 
 Client SDK codegen runs in watch mode (no port) and regenerates on API/gateful changes.
 
diff --git a/package.json b/package.json
index 4b2d7903a..a0e76062e 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
     "indexer": "dotenv -- turbo run --filter=@anticapture/indexer",
     "gateful": "dotenv -- turbo run --filter=@anticapture/gateful",
     "authful": "dotenv -- turbo run --filter=@anticapture/authful",
+    "user-api": "dotenv -- turbo run --filter=@anticapture/user-api",
     "api": "dotenv -- turbo run --filter=@anticapture/api",
     "codegen": "dotenv -- node scripts/wait-for-gateful.mjs && dotenv -- turbo run codegen",
     "client": "turbo run --filter=@anticapture/client",
diff --git a/scripts/dev.sh b/scripts/dev.sh
index 8ca6a3e0c..abc5532aa 100755
--- a/scripts/dev.sh
+++ b/scripts/dev.sh
@@ -27,7 +27,8 @@ PORT_GATEFUL=4001
 PORT_DASHBOARD=3000
 PORT_ADDRESS_ENRICHMENT=3001
 PORT_RELAYER=3002
-PORTS=("$PORT_INDEXER" "$PORT_API" "$PORT_GATEFUL" "$PORT_DASHBOARD" "$PORT_ADDRESS_ENRICHMENT" "$PORT_RELAYER")
+PORT_USER_API=4003
+PORTS=("$PORT_INDEXER" "$PORT_API" "$PORT_GATEFUL" "$PORT_DASHBOARD" "$PORT_ADDRESS_ENRICHMENT" "$PORT_RELAYER" "$PORT_USER_API")
 
 # DAO name → short ID mapping (used to run the API)
 dao_id_for() {
@@ -58,6 +59,7 @@ C_CODEGEN="\033[33m"           # yellow
 C_DASHBOARD="\033[32m"         # green
 C_ADDRESS_ENRICHMENT="\033[96m" # bright cyan
 C_RELAYER="\033[93m"           # bright yellow
+C_USER_API="\033[95m"          # bright magenta
 C_SCRIPT="\033[90m"            # gray
 C_RESET="\033[0m"
 
@@ -247,6 +249,22 @@ else
   log "Skipping optional Address Enrichment (Railway CLI/service unavailable)"
 fi
 
+# 4. User API (optional; identity + drafts + API keys). Needs its own Postgres,
+# supplied by the Railway dev env — so it runs like enrichment: via `railway
+# run`, skipped when the service/CLI isn't available. When up, the dashboard's
+# /api/user proxy targets it; when skipped, auth/drafts UIs are simply inert.
+USER_API_AVAILABLE=false
+if railway_service_available "user-api"; then
+  log "Starting optional User API..."
+  run_with_prefix "$C_USER_API" "👤 user-api" "" "" railway run -e dev -s user-api pnpm user-api dev &
+  if wait_for_optional_port "$PORT_USER_API" "User API"; then
+    USER_API_AVAILABLE=true
+    export USER_API_URL="http://localhost:${PORT_USER_API}"
+  fi
+else
+  log "Skipping optional User API (Railway CLI/service unavailable)"
+fi
+
 # Watchdog: when API recovers after being down, touch the sentinel file so tsx reloads the gateful
 if [ "$RUN_API" = true ]; then
   (
@@ -295,6 +313,11 @@ if [ "$ADDRESS_ENRICHMENT_AVAILABLE" = true ]; then
 else
   printf "  ${C_ADDRESS_ENRICHMENT}💰 Enrichment${C_RESET} skipped (optional)\n"
 fi
+if [ "$USER_API_AVAILABLE" = true ]; then
+  printf "  ${C_USER_API}👤 User API${C_RESET}  http://localhost:${PORT_USER_API}\n"
+else
+  printf "  ${C_USER_API}👤 User API${C_RESET}  skipped (optional)\n"
+fi
 printf "  ${C_GATEFUL}🚪 Gateful${C_RESET}   http://localhost:${PORT_GATEFUL}\n"
 printf "  ${C_RELAYER}📡 Relayer${C_RESET}   http://localhost:${PORT_RELAYER}\n"
 printf "  ${C_CODEGEN}🤝 REST Client${C_RESET}    codegen + build watch\n"