Developer Guide

This guide teaches you how to work on the zmNinjaNg codebase. It is written for developers who may not have React experience, explaining concepts from first principles with real examples from the code.

New to React? Start with Chapter 2 (React Fundamentals), then Chapter 3 (Zustand).

Adding a feature? Read Chapter 9 (Contributing) for the workflow, then Chapter 6 (Testing).

Debugging? Check Chapter 8 (Common Pitfalls) for previously encountered bugs and their fixes.

Understanding the architecture? Chapter 5 (Component Architecture) explains file organization, and Chapter 11 (Application Lifecycle) explains the runtime flow.

• Introduction to zmNinjaNg Development
  • What is zmNinjaNg?
  • Who This Guide Is For
  • Code Examples
  • Getting Help
• React Fundamentals
  • The mental shift
  • JSX
  • Components
  • Props: data flowing in
  • State: data the component owns
  • Render: what triggers it
  • Hooks
  • useEffect: doing things after render
  • useRef: a value that survives renders without triggering one
  • useMemo and useCallback: stable references
  • Object identity: the bug that hides everywhere
  • React.memo: skipping unnecessary renders
  • Putting it together
  • Where to go next
• State Management with Zustand
  • Why Global State
  • What Zustand Gives You
  • Creating a Store
  • Reading State in Components
  • Actions
  • Persistence
  • Calling Stores Outside React
  • Reference Equality and Infinite Loops
  • Stores in zmNinjaNg
  • Store Pattern
  • Testing Stores
  • Common Patterns
• Pages and Views
  • Routing
  • Page Structure
  • Dashboard
  • Montage
  • Monitors
  • MonitorDetail
  • Events
  • ProfileForm
  • Secondary Views
  • Common Page Patterns
• Project Architecture
  • Directory Structure
  • Component Structure
  • Monitor Components
  • Dashboard Components
  • Event Components
  • Video Playback
  • Filter Components
  • QR Scanner
  • Common Components
  • UI Components
  • Settings Components
  • Kiosk Mode
  • Component Composition
  • Testing Data Attributes
  • Key Patterns
  • Component Communication
  • Platform Integrations (src/services/)
• Testing Strategy
  • Cross-Platform Architecture
  • Unit Tests
  • E2E Tests
  • Running Tests
  • Device Setup
  • Visual Regression
  • Testing Workflow
  • Debugging Tests
  • Troubleshooting
• API and Data Fetching
  • ZoneMinder API
  • HTTP Client Architecture
  • Server API (api/server.ts)
  • Monitor API Updates (api/monitors.ts)
  • Event API Updates (api/events.ts)
  • Monitor Exclusion
  • Monitor Groups API
  • Event Tags API
  • Adjacent Event Navigation
  • Notifications API
  • Event Poller Service
  • WebSocket Notification Service
  • End-to-end Flow: Viewing Monitors
  • Error Handling
  • ZoneMinder Streaming Protocol
• Common Pitfalls
  • React Pitfalls
  • Zustand Pitfalls
  • React Query Pitfalls
  • Testing Pitfalls
  • Performance Pitfalls
  • Internationalization Pitfalls
  • Cross-Platform Pitfalls
  • Platform-Specific Pitfalls
  • Security Pitfalls
  • Checklist: Pre-Code Review
• Contributing to zmNinjaNg
  • Before You Start
  • Development Workflow
  • Code Review Guidelines
  • Common Contribution Scenarios
  • Style Guide
  • Mobile Development
  • Getting Help
  • License
  • Recognition
• Key Libraries
  • UI and Visualization
  • Data and Logic
  • Mobile and Platform
  • Internationalization
  • Constants Organization
• Application Lifecycle
  • 1. The Entry Point (index.html → main.tsx)
  • 2. Bootstrapping Phase (App.tsx)
  • 3. The Authentication Flow
  • 4. The “Main Loop” (Runtime)
  • 5. Mobile Lifecycle (Capacitor)
  • 6. Navigation Lifecycle
• Shared Services and Reusable Components
  • Shared Services (lib/)
  • Reusable UI Components
  • Shared Hooks (hooks/)
  • Reusable Domain Components
  • Usage Matrix
  • Adding New Shared Services
  • Token freshness gate
• External Network Endpoints
  • Endpoints
  • Notes
• Go2RTC WebRTC Streaming Integration
  • Overview
  • Architecture
  • Stream Selection Logic
  • Fallback Ladder
  • Implementation Details
  • StreamChannel
  • Fallback Chain
  • Controls
  • Type Definitions
  • Testing Strategy
  • Edge Cases Handled
  • Troubleshooting
  • Performance Considerations
  • Configuration Examples
  • Security Considerations
  • References
  • Future Enhancements

Quick Reference

State Types

Type	Where	Example	When to Use
Local	useState	Form inputs, UI toggles	Component-specific, temporary
Global	Zustand stores	Current profile, settings	Shared across components
Server	React Query	Monitor list, events	Data from ZoneMinder API

File Organization

app/src/
├── api/          # API functions (thin wrappers around HTTP client)
├── components/   # React components (visual)
├── hooks/        # Custom React hooks (component logic)
├── lib/          # Pure utilities (no React dependencies)
├── pages/        # Route-level views
├── services/     # Platform-specific code (Capacitor plugins)
├── stores/       # Global state (Zustand)
└── locales/      # i18n translations (en, de, es, fr, zh)

Development Quick Start

cd app
npm install
npm run dev      # Start development server
npm test         # Run unit tests
npm run build    # Build for production

Also see the AGENTS.md file for the full development guidelines and checklists.