# NexusCRM Developer Guide & Best Practices

> **Note**: Formerly `PRD.md`. This guide consolidates development standards and lessons learned.

## Technical Standards

### 1. Modal & Overlay Components
- **Use React Portal**: All modals must use `createPortal(content, document.body)`
- **Z-Index Standard**: Use `z-[100]` for all modal overlays
- **Reason**: Prevents stacking context issues where fixed headers appear above modals

```tsx
import { createPortal } from 'react-dom';

return createPortal(
    <div className="fixed inset-0 z-[100] ...">
        {/* modal content */}
    </div>,
    document.body
);
```

### 2. Schema & Constants
- **Single Source of Truth**: All system schema definitions come from `system_tables.json`
- **Generated Code**: Use code generation for Go models and TypeScript types
- **No Magic Strings**: Always use generated constants for field/table names

### 3. Type Safety
- Replace `any` with `unknown` in error handling
- Use generated types from `generated-schema.ts`
- Avoid `as any` casts - refactor instead

### 4. UI Patterns
- Use toast notifications instead of `console.error`
- Feature flags for configurable behaviors (e.g., `ENABLE_AUTO_FILL_API_NAME`)
- Take screenshots before/after UI operations for verification

### 5. API & Backend Proxy
- **Development Proxy**: `vite.config.ts` uses `REACT_APP_BACKEND_URL` to determine the API target.
- **Switching Backends**:
  - `http://localhost:3001` -> Local Go Backend
  - `https://test.salesforce.com` -> Salesforce Sandbox
- **Salesforce Mode**: The proxy automatically handles `secure: false` and `cookieDomainRewrite` when a Salesforce URL is detected.


## Process Standards

### Server Management
```bash
# Backend
./backend/restart-server.sh

# Frontend (requires TTY)
npm run dev
```

### Code Changes
1. Audit affected files with grep before widespread changes
2. Fix base/reusable components first
3. Run `npm run lint` after each batch
4. Browser verification for UI changes

### Documentation
- Keep walkthroughs concise with before/after comparisons
- Embed verification screenshots
- Update docs in sync with code