Run the frontends (saas-2.0 & UI2.0)

The super-repo ships two Next.js frontends. Both are, confusingly, named agent-synth in their package.json — but they are different apps:

• Directorybackend/core/

  • Directorysoundverse-saas-2.0/ the product — Next.js 15 SPA + BFF, wired to the whole backend

    • …
  • DirectoryUI2.0/ a sandbox — Next.js 16 in-browser studio, no backend

    • …

Only soundverse-saas-2.0 talks to the fleet. It is a client-only SPA (the entire product UI, rendered ssr:false) plus a thin server-side BFF whose app/api/* route handlers proxy every data call to core-gateway-consumer over gRPC — the browser never speaks gRPC and never holds a bearer token. UI2.0 is a standalone design/product playground with zero backend wiring; you can run it with nothing else booted.

	soundverse-saas-2.0	UI2.0
Role	The real product Deployed	Studio sandbox Not wired to backend
Stack	Next.js 15, React 19, Auth.js v5 (next-auth beta)	Next.js 16, React 19
Backend	BFF → core-gateway-consumer (gRPC)	None — no gRPC/proto/Connect deps
Auth	Logto OIDC (bearer stays server-side)	None
Tracked branch	staging	UI2.0NextJS
Local port	3000	3001 (compose) / 3000 (bare)

Full architecture lives in Frontend architecture (SPA + BFF); this page is just how to run them.

Run soundverse-saas-2.0 from source

This is the fast iteration path. It needs the backend already running — bring it up first via Quick start with docker-compose or Run the full stack from source.

Node version

Node 20+ (22 LTS is what the fleet and the UI2.0 compose service use). There is no engines pin in package.json; Next.js 15 needs Node ≥ 18.18 and Next.js 16 (UI2.0) needs Node ≥ 20.9.

1. Enter the repo. From the super-repo, the submodule is at soundverse-saas-2.0/ (run git submodule update --init soundverse-saas-2.0 first if it’s empty).

2. Create .env.local. Copy the checked-in template and fill in the auth + upstream vars (names only — never commit real values):

   soundverse-saas-2.0/

   cp .env.local.example .env.local

3. Install and run:

   npm install
   npm run dev              # Next.js dev server on http://localhost:3000
   npm run dev -- -p 4000   # if 3000 is taken

4. Sign in. Login is OIDC against Logto — you need a working Logto app (see Configure Logto OIDC) and the AUTH_LOGTO_* vars below. Without them the app boots but you can’t authenticate.

Minimum local env

The full set is in .env.local.example; the ones you actually need to log in and generate:

Var (name only)	Purpose
AUTH_SECRET	Encrypts the server-side Auth.js session JWT (openssl rand -base64 32).
AUTH_LOGTO_ID / AUTH_LOGTO_SECRET / AUTH_LOGTO_ISSUER / AUTH_LOGTO_RESOURCE	The Logto OIDC application. AUTH_LOGTO_ISSUER ends in /oidc; AUTH_LOGTO_RESOURCE (the API-resource indicator) is required so Logto mints a JWT, not an opaque token, that core-identity can validate against the JWKS.
CORE_GATEWAY_CONSUMER_GRPC	The consumer gateway host:port the BFF proxies to. Use localhost:8082 against a compose backend (the gateway’s host-mapped port); use core-gateway-consumer:8080 when the frontend itself runs inside the compose network.
AGENT_TOOL_ID	The generation.tools row id of the registered agent tool — required for Agent One chat (the BFF falls back to this when a request omits a tool id).
STREAM_PROXY_SECRET	Signs the short-lived tokens for the same-origin audio streaming proxy — required for playback.

.env.local.example also carries optional wiring: CORE_BILLING_GRPC (subscription-tier lookups → core-billing), CORE_DNA_API_URL, LEGACY_BACKEND_URL (the read-only legacy compat layer), and INTERNAL_RPC_SECRET. See the env var catalog for what each points at, and What works offline vs. what needs secrets for which features degrade gracefully without them.

npm scripts

From package.json:

Script	Does
dev	next dev — the local dev server.
build	next build — produces the output: "standalone" server bundle.
start	next start — serve a production build.
lint	eslint .
typecheck	tsc --noEmit
test:agentone / test:dna	node --test unit suites for the Agent One transport and DNA lib.

NEXT_PUBLIC_* is baked in at build time (a deploy trap, not a local one)

Any NEXT_PUBLIC_* var (e.g. NEXT_PUBLIC_ENVIRONMENT, NEXT_PUBLIC_BUILD_SHA) is substituted with a string literal by next build into both the client and server bundles — setting it as an Azure Container Apps runtime env does nothing for the browser. It must be present during the build, passed as a Docker --build-arg. Locally you don’t hit this: next dev reads .env.local automatically. It bites only the containerized deploy path, and .dockerignore strips .env* from the build context, so an un-passed public var builds as undefined. Server-only vars (CORE_GATEWAY_CONSUMER_GRPC, AUTH_*, AGENT_TOOL_ID) are read at runtime and must not be prefixed NEXT_PUBLIC.

Run both frontends via docker-compose

make up-frontend (the frontend compose profile) builds the backend and both frontends:

backend/core/

make up-frontend

• soundverse-saas-2.0 — built as a production standalone image and served on host 3000. Inside the compose network it points CORE_GATEWAY_CONSUMER_GRPC at core-gateway-consumer:8080 and uses the shared REDIS_ADDR for the {env}:saas: refresh-token key namespace.
• ui2 — UI2.0, on host 3001. It has no Dockerfile: it runs a stock node:22-bookworm-slim in dev mode with ./UI2.0 bind-mounted (npm install && npm run dev), so edits hot-reload without an image build.

Use make up-frontend for a faithful production-shaped run; use bare npm run dev (above) for tight iteration on saas-2.0.

Run UI2.0 (the standalone studio)

Sandbox — not wired to backend

UI2.0 (branch UI2.0NextJS, Next.js 16 + React 19) is a client-only in-browser music studio. It shares the saas-2.0 SPA shape — one catch-all app/[[...slug]]/page.tsx → an ssr:false island — but has no gRPC, no proto, no Logto. Generation is demo/optimistic (a local studio side-effect or an optimistic PROCESSING → DONE), and its only network egress is a chat to a demo LiteLLM proxy plus a direct in-browser Anthropic call from its synth patch panel. You can run it with nothing else booted:

UI2.0/

npm install
npm run dev   # http://localhost:3000

Or let make up-frontend run it for you as the ui2 service on host 3001.

Two apps, one package name

Both frontends declare "name": "agent-synth" in package.json — don’t let that fool you into thinking they’re the same build. soundverse-saas-2.0 is the deployed product; UI2.0 is a sandbox that never calls CreateGeneration.

Related

• Frontend architecture (SPA + BFF) — how the SPA + BFF actually work
• Configure Logto OIDC — the auth app the sign-in flow needs
• Configuring .env — the env pattern and injection rules
• What works offline vs. what needs secrets — which features need a credential
• BFF routes → RPC map — every /api/* route and the RPC behind it
• core-gateway-consumer — the upstream the BFF proxies to