Resolving locale, route permissions, and workspace projection.
Current scope: Guest
Category: 90_stabilization | Version: v1.0.0
Owner: DOCUMENT_CUSTODIAN | Review cycle: 90 days
Approval authority: Unspecified
Documentation portal is read-only. Editing and mutation endpoints are disabled.
Kvary platform is originally created in Georgian. Where a Georgian version exists, Georgian is authoritative for platform UI, documentation, and legal interpretation.
Translations into other languages are provided for convenience. Some records may originate in other languages and carry their own source or legal locale for a specific flow, but where a Georgian version is available, the Georgian version prevails for platform-level wording and interpretation.
Metadata incomplete: Document ID, Version, Status, Owner Role, Last Review Date, Next Review Date, Change Log
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.
Root npm run dev starts these services:
apps/web -> http://localhost:3000services/api -> http://localhost:4001services/svc-auth -> http://localhost:4100services/svc-tenders -> http://localhost:4020services/svc-risk -> http://localhost:4200postgres -> postgres://kvary:kvary@127.0.0.1:5432/kvaryFor 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/webWEB_PORT=3000 for apps/webFRONTEND_BASE_URL=http://localhost:3000 for svc-authGOOGLE_OIDC_REDIRECT_URI=http://localhost:3000/auth/google/callback for svc-authThis is operationally important for Google login. Local OIDC callback origin must stay stable and match the OAuth app configuration.
The controlling script is:
Relevant root dev commands:
dev:auth -> PORT=4100dev:api -> PORT=4001dev:tenders -> PORT=4020dev:web -> apps/webThe standard public web portal uses:
NEXT_PUBLIC_API_BASE_URL=http://localhost:4001/api/v1That means:
apps/web -> services/api (4001)services/api -> services/svc-tenders (4020) for tenders/auctions related readsCurrent gateway defaults:
TENDERS_SERVICE_URL ?? http://localhost:4020AUCTIONS_SERVICE_URL ?? TENDERS_SERVICE_URL ?? http://localhost:4020Files:
The internal Next proxy routes are same-origin browser routes under apps/web/src/app/api/....
These prefer:
AUCTION_DECLARATION_SERVICE_URLTENDERS_SERVICE_URLhttp://localhost:4020Examples:
/api/auctions/declarations/.../api/auctions/internal/api/output-allocations/...These use:
TENDERS_SERVICE_URLhttp://localhost:4020Examples:
/api/tenders/declarations/.../api/tenders/internalFiles:
For current root dev setup, the intended upstream is:
http://localhost:4020Recommended 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
/me and refresh pathThe web auth bootstrap uses:
NEXT_PUBLIC_AUTH_GATEWAY_BASE=http://localhost:4001/api/v1/authSo:
/auth/me/auth/refresh/auth/logingo through services/api at 4001, not directly to svc-auth.
Files:
Live auth permissions are currently derived from:
auth_accounts.roleCurrent declaration-related role truth:
AUCTION_DECLARER
auction:create-draftauction:mark-readyauction:declareTENDER_DECLARER
MARKET_DECLARER
auction:create-draftauction:mark-readyauction:declaretender:create-drafttender:mark-readytender:declareADMIN
admin:accessImportant:
admin:access is not the same as auction/tender declaration capability.admin:access.Public routes remain public-only:
GET /auctionsGET /auctions/:idGET /tendersGET /tenders/:idPublic routes must not expose pre-announcement declaration states.
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:
DRAFTREADY_FOR_ANNOUNCEMENTANNOUNCEDdepending on mechanism-specific flow.
If any of these change:
apps/web/.env.localservices/api/.envservices/svc-tenders/.envservices/svc-auth/.envrestart the affected process at minimum.
Practical rule:
apps/webservices/apiservices/svc-tendersservices/svc-authIf the auth role on a user row changes:
svc-auth only if code changed