State Management

This document explains how state is managed in the project, including when to use React context, custom stores, and best practices.

---

Approaches Used

• React Contexts: For global state (auth, user, org, tab, etc.)
• Custom Stores (e.g., Zustand): For feature or app-wide state that needs to be shared outside of React's tree.

---

When to Use Context vs. Store

Use Case	Use Context?	Use Store?
Auth/user info	Yes	Sometimes
Theme/tabs	Yes	Sometimes
Feature state (tasks)	Sometimes	Yes
Cross-page state	No	Yes
Local UI state	No	No

• Context: Use for global, rarely-changing state or when you need to provide data deep in the tree.
• Store: Use for feature state, cross-page state, or when you need to update state outside React components.

---

How to Add New State

1. Global State:

   • Add a new context in src/contexts/.
   • Provide it at the top level (usually in App.tsx).
   • Use the useContext hook to access it.

2. Feature State:

   • Add a new store in src/stores/ (e.g., useTasksStore.ts).
   • Use the store hook in any component that needs the state.

---

Best Practices

• Keep state as close to where it's used as possible.
• Avoid prop drilling by using context or stores.
• Use TypeScript types for all state.
• Reset state on logout or navigation if needed.
• Use selectors or custom hooks to avoid unnecessary re-renders.

---

For more, see ARCHITECTURE.md or ask a maintainer.