feat: split admin into dedicated web surface

README.md

@@ -19,8 +19,10 @@ LocaleScope is a React + Vite app for researching local markets, saving business
    - `COOKIE_SECRET`
    - `GOOGLE_MAPS_SERVER_KEY`
    - Stripe env vars below if you want to test billing locally
-3. Run the frontend:
+3. Run the user frontend:
    `npm run dev:web`
+4. Run the admin frontend (dedicated surface):
+   `npm run dev:admin`
 
 The local backend and scripts load both `.env` and `.env.local`, with `.env.local` taking precedence, so you can keep the full local setup in one file during development.
 
@@ -42,8 +44,8 @@ If you open the app from another machine on your LAN, set `VITE_API_BASE_URL` an
 - [ ] Copy `.env.example` to `.env.local` and fill required keys: `DATABASE_URL`, `COOKIE_SECRET`, `GOOGLE_MAPS_SERVER_KEY`, `VITE_GOOGLE_MAPS_PLATFORM_KEY`, and Stripe keys if testing billing
 - [ ] Run migrations: `npm run migrate`
 - [ ] Set `ALLOW_ADMIN_BOOTSTRAP=true` and define `ADMIN_BOOTSTRAP_TOKEN`
-- [ ] Start web, API, and worker: `npm run dev:web`, `npm run dev:api`, `npm run dev:worker`
-- [ ] Visit `/auth` and create the first site admin
+- [ ] Start app web, admin web, API, and worker: `npm run dev:web`, `npm run dev:admin`, `npm run dev:api`, `npm run dev:worker`
+- [ ] Visit the admin surface and create the first site admin
 - [ ] Disable bootstrap after first admin creation: `ALLOW_ADMIN_BOOTSTRAP=false`
 - [ ] Verify admin billing access at `/api/admin/billing/workspaces`
 
@@ -56,7 +58,7 @@ Bootstrap mode is only needed when no active application admin exists.
 
 1. Run migrations first: `npm run migrate`
 2. Set `ALLOW_ADMIN_BOOTSTRAP=true` and `ADMIN_BOOTSTRAP_TOKEN` in your env file
-3. Visit `/auth`, then create the first account in "Create first site admin" mode
+3. Visit the dedicated admin surface, then create the first account in "Create first site admin" mode
 4. After the first admin is created, set `ALLOW_ADMIN_BOOTSTRAP=false`
 
 ## Stripe Billing Setup
@@ -127,18 +129,26 @@ Safe mutation pilot:
     - `POSTGRES_USER`
     - `POSTGRES_PASSWORD`
     - `WEB_PORT`
+    - `ADMIN_WEB_PORT`
     - `APP_PORT`
     - `COOKIE_SECRET`
     - `GOOGLE_MAPS_SERVER_KEY`
-    - `VITE_API_BASE_URL` (use `/api` when web and API share a domain via the nginx proxy)
+    - `VITE_API_BASE_URL` (use `/api` when web/admin and API share a domain via the nginx proxy)
     - `VITE_GOOGLE_MAPS_PLATFORM_KEY`
 2. Create the shared Docker network if it does not exist:
    `docker network create locale-all || true`
 3. Build and start the full stack:
    `docker compose up --build`
 
-The Compose stack starts PostGIS, waits for the database to become healthy, runs migrations automatically, and then starts the API, worker, and web containers.
-With the default `.env.example` values, the app is exposed on `http://localhost:3000` and the API on `http://localhost:4000`.
+The Compose stack starts PostGIS, waits for the database to become healthy, runs migrations automatically, and then starts the API, worker, user-web, and admin-web containers.
+With the default `.env.example` values, the user app is exposed on `http://localhost:3000`, the admin app on `http://localhost:3001`, and the API on `http://localhost:4000`.
+
+## App and Admin Surfaces
+
+- User and admin UIs now run on separate frontend surfaces/build targets.
+- The main app no longer links to or renders admin routes/tabs.
+- Admin tasks live on the dedicated admin surface and continue using the same API/session auth.
+- `APP_ORIGIN` should include both origins for CORS/session checks, for example: `https://localescope.com,https://admin.localescope.com`.
 
 ## Database Layout