04 — Your first contribution to `admin_console_R`¶

A walkthrough.

1. Pick a small first task¶

Good first tickets:

Doc fix in ../../audit/admin_console_R/.
A console.log cleanup from ../../code-inspect/admin_console_R.md.
Add a .env.example. The repo doesn't have one — create it based on src/config/env.ts. Real value: a future new developer doesn't have to grep the codebase for env vars.
Move the hardcoded Apptype: 'admin-console' in services/api.ts to use ENV.APP_TYPE. Verify the BE still accepts the value (it should). This is finding F-2 in the security audit.
Add a missing role gate to one of the sidebar nav items. Identify a nav item that lacks an if (user?.role === ENV.<ROLE>) check; add it.

Avoid for your first PR: removing the Lovable.dev script (cross-team decision needed), refactoring the verbose <ProtectedRoute><AppLayout>... wrapping, adding new global state.

2. The edit-run-verify loop¶

cd ~/src/someli/admin_console_R

# Branch
git checkout dev
git pull origin dev
git checkout -b fix/first-pr

# Run
npm run dev                          # http://localhost:8080

# Verify in browser; HMR is fast

For vite.config.ts or tsconfig.app.json changes, restart npm run dev.

3. Entry points to know — a 20-minute reading tour¶

src/main.tsx (tiny). Read.
src/App.tsx. Read the whole file — provider stack + every route.
src/config/env.ts. The env-var surface. Short.
src/context/AuthContext.tsx (~150 lines). How login/logout/token state work.
src/components/auth/ProtectedRoute.tsx. Short. How protected pages gate.
src/components/layout/AppLayout.tsx + Sidebar.tsx.
src/services/api.ts. The 184-line API surface.
src/pages/Login.tsx + src/components/auth/LoginForm.tsx. End-to-end login example.
One non-trivial page — src/pages/Accounts.tsx if it's the largest.

After this, you can place 95% of new code.

4. Reading-around your task¶

Grep:
```
grep -rn 'mySearchTerm' src/
```
TypeScript helps a lot here. Hover types in your editor; jump to definition (F12 in VS Code).
Run the linter:
```
npm run lint
```
Audit docs:
Architecture → ../../audit/admin_console_R/architecture-overview.md
API consumption → ../../audit/admin_console_R/api-consumption.md
Auth → ../../audit/admin_console_R/authentication-client.md
Security → ../../audit/admin_console_R/security.md
Routing / state → ../../audit/admin_console_R/routing-and-state.md

5. Manual testing¶

No test suite.

Happy path.
Logged-out — does ProtectedRoute redirect to /login?
Wrong role — pick a role that shouldn't see the feature; verify the nav item is hidden AND the page returns/redirects if accessed directly.
Slow network — Chrome DevTools throttling. Does the loading state render?
TanStack Query — open the React Query devtools (you can install the devtools package locally to inspect query state).
Browser refresh — does the user stay logged in (token rehydrates from localStorage)?

6. Useful local helpers¶

React DevTools¶

Install React Developer Tools (Chrome / Firefox extension). Inspect component tree, hooks, props.

TanStack Query DevTools¶

Add the devtools temporarily:

npm install --save-dev @tanstack/react-query-devtools

And in App.tsx:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
// inside QueryClientProvider:
<ReactQueryDevtools initialIsOpen={false} />

Remove before committing (don't ship devtools in production).

Inspecting `localStorage`¶

DevTools → Application → Local Storage. The auth token and user object live here.

7. Lint and PR¶

npm run lint                  # fix issues before pushing

git add -p
git commit -m "Add .env.example with all VITE_* vars from src/config/env.ts"
git push -u origin fix/first-pr
# Open PR on github.com/Someli-ai/admin_console_R → dev

PR description:

Why / what
Screenshots for any UI change (this is a UI-heavy repo)
Manual test plan + which roles you tested
Confirm npm run lint passes

8. After merge¶

No in-repo CI. Ask the team how dev deploys work.

git checkout dev && git pull
git branch -d fix/first-pr

9. Common first-PR mistakes¶

Mistake	Why it bites	Avoid by
Running `yarn install` or `bun install` instead of `npm install`	Updates the unused lockfile; produces a confusing diff	Use `npm install` only; revert stray lockfile diffs
`as any` to silence TS errors	Defeats the only safety net in the platform	Type things properly; ask if stuck
Adding a parallel state mechanism (Redux, Zustand, …)	TanStack Query + AuthContext + local `useState` is sufficient	Use what's there
Breaking the role-gated sidebar	Wrong users see options they shouldn't	Always gate by `user?.role === ENV.<ROLE>`
Editing `src/components/ui/<primitive>.tsx` and assuming it's vendored	These ARE owned by you (shadcn convention) — but if your change is generic, consider whether other primitives need the same change
Forgetting `Apptype` header alignment with BE	The BE sometimes branches on it	Match what `Someli-admin-api` expects
Forgetting that role IDs come from env vars	If env is wrong, all role checks misbehave	Verify `VITE_*` role IDs match the BE's role_type values
Adding a CDN script tag	Joins the Lovable.dev script in the "no SRI" category	Add as an npm dependency instead
Committing `dist/`	It's a generated artefact	`.gitignore` should cover it; double-check `git status` before pushing

Next¶

→ 05-where-to-look.md.

04 — Your first contribution to admin_console_R¶