01 — `admin_console_R` setup¶

You've finished ../00-workstation-setup.md. Now stand up admin_console_R.

1. Clone¶

cd ~/src/someli
git clone git@github.com:Someli-ai/admin_console_R.git
cd admin_console_R
git checkout dev          # plain dev/uat/main

Verify with the team if the active dev branch differs.

2. Pin Node 20¶

nvm use 20.18.3
node --version
npm --version             # 10.x

3. Install with npm¶

The repo ships three lockfiles: package-lock.json, yarn.lock, and bun.lockb. npm is the canonical one — confirmed by the audit. Use npm install, not yarn or bun.

npm install

~2–3 minutes first time.

Junior gotcha: if you accidentally run yarn install first, the existing yarn.lock gets updated and you'll commit a confusing diff. Use npm install only. If you see a stray yarn.lock update in your git status, revert it.

4. The `.env` file¶

The repo does not ship a .env.example. Ask the team for the dev .env.

The file lives at the project root: admin_console_R/.env. Vite reads VITE_* prefixed variables at build time.

Variables you need¶

Var	Required	What
`VITE_API_URL`	yes	URL of `Someli-admin-api` (`http://localhost:5004` or team's dev URL)
`VITE_BASE_URL`	optional	(consumer not located in the audit; probably for cross-app links)
`VITE_APP_URL`	optional	Links into the customer app
`VITE_APP_TYPE`	yes	Should be sent as base64 `Apptype` header — but `api.ts` currently hardcodes `"admin-console"` instead (known finding)
`VITE_USER_APP_TYPE`	optional	For impersonation flows
`VITE_ACCOUNT_MANAGER`	yes	Role ID for "Account Manager"
`VITE_SUPER_ADMIN`	yes	Role ID for "Super Admin"
`VITE_ADMIN`	yes	Role ID for "Admin"
`VITE_DEVELOPER`	yes	Role ID for "Developer"
`VITE_DESIGNER`	yes	Role ID for "Designer"
`VITE_SOMELI_DEV_URL`	optional	Dev environment of customer app (cross-app links)

The role-IDs-as-env-vars pattern is unusual. The backend's role_type values are not env-driven; the FE's are. Misalignment between backend and FE causes wrong-role bugs that look like permissions chaos. Verify the role IDs match the BE values before assuming anything.

5. Start the dev server¶

npm run dev

Vite dev server starts on http://localhost:8080 (port set in vite.config.ts, not the Vite default 5173).

If someli-platform or Someli-Designer is also running, they default to port 3000 — no collision.

vite.config.ts → server.allowedHosts: ["admin.someli.ai"] — only relevant if Vite is reverse-proxied through admin.someli.ai during dev. Verify with the team whether your dev setup uses this; otherwise it's vestigial.

6. Smoke test¶

Open http://localhost:8080. You'll see the Login page.

Log in with a staff account (ask the team). After login, you should land on /accounts (or another protected page).

Watch the Network tab — requests go to VITE_API_URL. The hardcoded Apptype: admin-console header should be on every request.

7. Production build¶

npm run build              # vite build → dist/
npm run build:dev          # vite build --mode development — for staging-style debug builds
npm run preview            # serve the dist/ for verification

There is no npm run start — production hosting strategy is not documented in-repo. Verify with the team.

8. Linting¶

npm run lint               # ESLint 9 flat config

This is the only repo in the platform with a working lint command. Use it before opening a PR.

There is no Prettier and no pre-commit hook.

9. You're done¶

If npm run dev runs, you can hit http://localhost:8080, and login works against Someli-admin-api, you are ready.

Next: 02-stack.md.

Troubleshooting¶

Symptom	Likely cause
`npm install` produces a diff in `yarn.lock` or `bun.lockb`	You're committing too much — only `package-lock.json` should change. Revert the stray lockfile updates.
Vite fails to start with TypeScript errors	Run `npm run lint` to see what TS thinks; `tsconfig.app.json` defines the compile config
Login fails / hangs	Network tab — is `VITE_API_URL` correct? Is the BE reachable?
`Apptype` header missing	`api.ts` may have lost the hardcoded `"admin-console"` — verify by inspecting request headers
HMR overlay never appears	`vite.config.ts → server.hmr.overlay: false` — overlay is disabled. Errors show in the terminal instead.
TanStack Query queries refetch on every focus	Default `refetchOnWindowFocus: true` — set query options in `App.tsx → QueryClient` config if you want different behaviour
Wrong role lets a user see a page they shouldn't	`VITE_*` role IDs don't match what the BE returns — cross-check with `Someli-admin-api`

01 — admin_console_R setup¶