Local Runtime And Auth Source Of Truth

This note is the current repo-local source of truth for the local dev runtime chain used by declaration flows and the standard public portal paths.

Runtime chain

Root npm run dev starts these services:

• apps/web -> http://localhost:3000
• services/api -> http://localhost:4001
• services/svc-auth -> http://localhost:4100
• services/svc-tenders -> http://localhost:4020
• services/svc-risk -> http://localhost:4200
• postgres -> postgres://kvary:kvary@127.0.0.1:5432/kvary

For npm run dev:one, the bootstrap script now keeps the web origin fixed on http://localhost:3000 and aligns auth OIDC runtime env to that same frontend origin:

• WEB_PORT=http://localhost:<chosen-port> for apps/web
• WEB_PORT=3000 for apps/web
• FRONTEND_BASE_URL=http://localhost:3000 for svc-auth
• GOOGLE_OIDC_REDIRECT_URI=http://localhost:3000/auth/google/callback for svc-auth

This is operationally important for Google login. Local OIDC callback origin must stay stable and match the OAuth app configuration.

The controlling script is:

• package.json

Relevant root dev commands:

• dev:auth -> PORT=4100
• dev:api -> PORT=4001
• dev:tenders -> PORT=4020
• dev:web -> apps/web

Public list/detail path

The standard public web portal uses:

• NEXT_PUBLIC_API_BASE_URL=http://localhost:4001/api/v1

That means:

• apps/web -> services/api (4001)
• services/api -> services/svc-tenders (4020) for tenders/auctions related reads

Current gateway defaults:

• tenders:
  • TENDERS_SERVICE_URL ?? http://localhost:4020
• auctions:
  • AUCTIONS_SERVICE_URL ?? TENDERS_SERVICE_URL ?? http://localhost:4020

Files:

• apps/web/.env.local
• services/api/src/routes/tenders.ts
• services/api/src/routes/auctions.ts

Internal declaration proxy path

The internal Next proxy routes are same-origin browser routes under apps/web/src/app/api/....

Auction/internal allocation-related proxies

These prefer:

1. AUCTION_DECLARATION_SERVICE_URL
2. TENDERS_SERVICE_URL
3. fallback http://localhost:4020

Examples:

• /api/auctions/declarations/...
• /api/auctions/internal
• /api/output-allocations/...

Tender declaration/internal proxies

These use:

1. TENDERS_SERVICE_URL
2. fallback http://localhost:4020

Examples:

• /api/tenders/declarations/...
• /api/tenders/internal

Files:

• apps/web/src/app/api/auctions/declarations/drafts/route.ts
• apps/web/src/app/api/auctions/internal/route.ts
• apps/web/src/app/api/output-allocations/route.ts
• apps/web/src/app/api/tenders/declarations/drafts/route.ts
• apps/web/src/app/api/tenders/internal/route.ts

For current root dev setup, the intended upstream is:

• http://localhost:4020

Recommended local web env:

NEXT_PUBLIC_API_BASE_URL=http://localhost:4001/api/v1
NEXT_PUBLIC_AUTH_GATEWAY_BASE=http://localhost:4001/api/v1/auth
AUCTION_DECLARATION_SERVICE_URL=http://localhost:4020

For direct manual service startup outside dev:one, keep the local web/auth pair aligned:

# services/svc-auth/.env or shell env
FRONTEND_BASE_URL=http://localhost:3000
GOOGLE_OIDC_REDIRECT_URI=http://localhost:3000/auth/google/callback

Auth /me and refresh path

The web auth bootstrap uses:

• NEXT_PUBLIC_AUTH_GATEWAY_BASE=http://localhost:4001/api/v1/auth

So:

• /auth/me
• /auth/refresh
• /auth/login

go through services/api at 4001, not directly to svc-auth.

Files:

• apps/web/src/lib/auth/useCurrentUser.ts
• apps/web/src/lib/auth/client.ts
• apps/web/.env.local

Declaration-related live auth role mappings

Live auth permissions are currently derived from:

• auth_accounts.role
• mapped in services/svc-auth/src/server.ts

Current declaration-related role truth:

• AUCTION_DECLARER

  • auction:create-draft
  • auction:mark-ready
  • auction:declare

• TENDER_DECLARER

  • currently not mapped
  • no live permission payload is emitted for this role at the moment

• MARKET_DECLARER

  • auction:create-draft
  • auction:mark-ready
  • auction:declare
  • tender:create-draft
  • tender:mark-ready
  • tender:declare

• ADMIN

  • admin:access

Important:

• admin:access is not the same as auction/tender declaration capability.
• Declaration UI visibility should align to the declaration permission set, not assume admin:access.

Public vs internal/operator routes

Public

Public routes remain public-only:

• GET /auctions
• GET /auctions/:id
• GET /tenders
• GET /tenders/:id

Public routes must not expose pre-announcement declaration states.

Internal/operator

Internal declaration and registry routes are capability-gated:

• /api/auctions/internal
• /api/auctions/declarations/...
• /api/output-allocations/...
• /api/tenders/internal
• /api/tenders/declarations/...

Internal views may expose:

• DRAFT
• READY_FOR_ANNOUNCEMENT
• ANNOUNCED

depending on mechanism-specific flow.

Restart rule when env changes

If any of these change:

• apps/web/.env.local
• services/api/.env
• services/svc-tenders/.env
• services/svc-auth/.env

restart the affected process at minimum.

Practical rule:

• if web env changes -> restart apps/web
• if gateway env changes -> restart services/api
• if tenders env changes -> restart services/svc-tenders
• if auth env or role mapping changes -> restart services/svc-auth

If the auth role on a user row changes:

• restart svc-auth only if code changed
• sign out / sign in again to mint a new token with the updated permissions