Development Workflow

How the team works — branching, PRs, code review, debugging, and fixing common issues.

Git Branching Strategy

Branch Type	Naming	Purpose	Example
main	`main` / `master`	Production-ready code. Auto-deploys.	—
feature	`feature/short-description`	New functionality	`feature/pipeline-filters`
fix	`fix/issue-description`	Bug fixes	`fix/save-crash-on-empty-config`
refactor	`refactor/area`	Code cleanup, no behavior change	`refactor/operator-config-panel`

Rules

Always branch from main
Keep branches short-lived (1-3 days)
One feature/fix per branch
Delete branch after merge

Commit Messages

Use clear, descriptive commit messages:

feat: add filter sidebar to pipeline list page

fix: prevent crash when saving operator with empty config

refactor: extract FormRenderer field types into separate files

docs: add testing guide to build section

Prefix	When to Use
`feat:`	New feature or capability
`fix:`	Bug fix
`refactor:`	Code restructuring, no behavior change
`style:`	Formatting, whitespace, missing semicolons
`docs:`	Documentation only
`test:`	Adding or updating tests
`chore:`	Build config, dependencies, tooling

Pull Request Process

Creating a PR

Push your branch: git push -u origin feature/my-feature
Open a PR against main
Fill in the PR template:

## What
Brief description of the change.

## Why
What problem does this solve or what feature does it add?

## How to Test
Steps to verify the change works:
1. Navigate to ...
2. Click ...
3. Verify ...

## Screenshots
(if UI changes)

PR Checklist (Before Requesting Review)

pnpm lint passes with no new errors
pnpm build succeeds (TypeScript check + production build)
Tested manually in the browser
No console.log left in code (use console.error sparingly for real errors)
No hardcoded URLs, tokens, or credentials
New files follow naming conventions (PascalCase components, camelCase hooks, kebab-case folders)
React Query mutations invalidate related queries on success
Error states handled (API failures show toast or inline error)

Code Review Guidelines

What Reviewers Look For

Area	Check
Correctness	Does it work? Edge cases handled?
API integration	Correct endpoint? Response parsed properly? Errors handled?
State management	Right layer? (React Query for server, Zustand for UI, RHF for forms)
Component structure	Reusing `@dtx/ui` components? Not reinventing existing patterns?
Types	TypeScript types explicit at boundaries? No `any`?
Side effects	Cleanup in useEffect? No memory leaks?
UX	Loading states? Error messages? Disabled buttons during mutations?

Review Turnaround

Aim for same-day reviews. If blocked, ping the reviewer.

Debugging Tips

API Issues

Chrome DevTools → Network tab is your primary tool for API debugging.

Symptom	What to Check
Request not sent	Is the mutation triggered? Check React Query DevTools.
401 Unauthorized	Token expired? Check `Authorization` header in Network tab. Keycloak refresh may have failed.
403 Forbidden	User doesn't have the required role. Check Keycloak realm roles.
404 Not Found	Wrong endpoint path? Check the service file and Vite proxy config.
422 Validation	Expand response body in Network tab — `errors[]` shows which fields failed.
CORS Error	Request going to wrong port? Check Vite proxy in `vite.config.ts`.
Empty response	Backend might return `204 No Content` — check if `parseApiResponse` handles it.

State Issues

React DevTools (browser extension):

Install React DevTools
Open DevTools → Components tab
Click any component to inspect its props, state, and hooks
Use the search bar to find components by name

React Query DevTools (built-in):

Look for the React Query floating icon in dev mode
Click to see all active queries, their status, and cached data
Useful for: stale data, failed queries, cache invalidation issues

Zustand DevTools:

usePipelineStore state: Check IndexedDB in DevTools → Application → IndexedDB
useWorkflowDesignerStore state: Check localStorage in DevTools → Application → Local Storage
useAccessManagementStore state: Check sessionStorage in DevTools → Application → Session Storage

Styling Issues

Problem	Solution
Class not applying	Check for Tailwind typo. Use Tailwind IntelliSense extension.
Dark mode broken	Verify `.dark-mode` class on root element. Check dark variant exists.
Layout shift	Check for missing `min-h`, `min-w`, or `flex-shrink-0`.
Z-index conflict	Modals use high z-index. Check `z-*` Tailwind utilities.

Troubleshooting Common Issues

Symptom	Cause	Fix
Login page doesn't load	Keycloak server not running	Start Keycloak or point `.env.local` to DEV environment
"Invalid redirect URI"	Keycloak client misconfigured	Add `http://localhost:3000/*` to valid redirect URIs in Keycloak admin
Token refresh fails	Realm or client ID mismatch	Verify `VITE_KEYCLOAK_REALM` and `VITE_KEYCLOAK_CLIENT_ID` in `.env.local`
Infinite login loop	Cookie conflict	Clear cookies for `localhost`, try incognito

Vite Dev Server

Symptom	Cause	Fix
Port 3000 already in use	Another process on the port	Kill the process: `lsof -i :3000` then `kill <PID>`
HMR not working	File watcher limit	Linux: increase `fs.inotify.max_user_watches`
Slow startup	Large `node_modules`	Run `pnpm store prune` to clean pnpm cache
Proxy errors (502)	Backend service not running	Start the backend service or update `.env.local` to point to DEV

pnpm Install

Symptom	Cause	Fix
"ERR_PNPM_PEER_DEP"	Peer dependency conflict	Check `pnpm-workspace.yaml` catalog for version mismatches
"command not found: pnpm"	pnpm not installed	`npm install -g pnpm@10`
Lockfile conflict	Different pnpm versions	Use the version in `packageManager` field of `package.json`
"EACCES permission denied"	File permission issue	Don't use `sudo`. Fix ownership: `chown -R $USER node_modules`

TypeScript Errors

Symptom	Cause	Fix
22 errors in `@dtx/ui` Select	Known issue — self-referencing imports in Select components	Tracked in Technical Debt. Does not block dev server, only blocks `pnpm build`.
"Cannot find module @/"	Path alias not resolved	Restart VS Code TypeScript server: Cmd+Shift+P → "TypeScript: Restart TS Server"
"Property does not exist"	Backend added a new field	Update the type definition in `types/{service}.types.ts`

Build Failures

Symptom	Cause	Fix
Type check fails	TypeScript strict mode	Fix the type error — don't use `// @ts-ignore`
Out of memory	Large build	Increase Node memory: `NODE_OPTIONS=--max-old-space-size=4096 pnpm build`
Missing dependency	Not in `pnpm-workspace.yaml` catalog	Add to catalog and run `pnpm install`

Development Environment Tips

Pointing to DEV Backend

If you don't have backend services running locally, update .env.local to proxy through the DEV environment:

VITE_API_BASE_URL=http://100.91.186.89:30000/api

The Vite dev proxy will forward requests to the remote backend.

Useful Browser Extensions

Extension	Purpose
React DevTools	Component tree, state, props inspection
Redux DevTools	Works with Zustand via middleware (optional)
JSON Viewer	Format JSON API responses in browser
Keycloak DevTools	Inspect tokens, roles, sessions

Git Branching Strategy​

Rules​

Commit Messages​

Pull Request Process​

Creating a PR​

PR Checklist (Before Requesting Review)​

Code Review Guidelines​

What Reviewers Look For​

Review Turnaround​

Debugging Tips​

API Issues​

State Issues​

Styling Issues​

Troubleshooting Common Issues​

Keycloak Login Failures​

Vite Dev Server​

pnpm Install​

TypeScript Errors​

Build Failures​

Development Environment Tips​

Pointing to DEV Backend​

Useful Browser Extensions​