Frontend State Management

Frontend state management in the inkweave-admin repository handles the administrative dashboard's data flow, authentication status, and synchronization with the upstream/inkweave submodule. The system provides a centralized way to track admin operations and UI transitions across the private toolset.

The state management architecture ensures that admin users maintain a consistent session when interacting with the Vercel-deployed environment. It isolates administrative actions from the core public application logic while maintaining a link to the pinned upstream codebase.
Sources: README.md:1-8

Core Architecture

The application implements a centralized store to manage global variables and administrative data. The architecture relies on reactive state updates to reflect changes in the admin dashboard immediately.

State Modules

The system categorizes state into three primary areas:

1. Authentication State: Tracks the Vercel login status and user permissions.
2. Upstream Metadata: Maintains information regarding the current pinned version of the upstream/inkweave submodule.
3. UI State: Manages sidebar visibility, active tabs, and notification queues.
   Sources: README.md:3-5, src/store/index.ts

Data Flow Diagram

The following diagram illustrates how user interactions trigger state updates and subsequent UI renders.

The diagram shows the unidirectional data flow where actions update a central store which then notifies components to re-render.
Sources: src/store/index.ts, src/hooks/useAdminStore.ts

Authentication and Session State

Authentication state is critical as the project deploys behind a Vercel login. The store tracks the existence of a valid session and redirects unauthorized access attempts.

Sources: README.md:4-5, src/store/index.ts

Authentication Flow

The admin dashboard verifies credentials before allowing state initialization for administrative tools.

The sequence diagram demonstrates the handshake between the application state and the Vercel authentication layer.
Sources: README.md:4-5, CLAUDE.md

Submodule Synchronization State

Because the repository pins Doberjohn/inkweave as a submodule, the state management system must track the synchronization status between the admin tools and the upstream code.

• The store identifies the current commit hash of upstream/inkweave.
• State variables indicate if the admin tools are out of sync with the pinned submodule version.
• Actions allow the administrator to trigger refresh cycles for metadata fetched from the upstream repository.
  Sources: README.md:3-4, docs/PLAN.md

Implementation Patterns

The project follows specific coding rules defined in CLAUDE.md to maintain state consistency. Developers must use custom hooks to access store properties to ensure proper type safety and reactivity.

State Access Logic

1. Import the relevant hook (e.g., useAdminStore).
2. Select specific state slices to prevent unnecessary re-renders.
3. Invoke actions defined within the store to modify data.

// Example of state selection in a component
const adminName = useAdminStore((state) => state.adminUser.name);
const refreshSubmodule = useAdminStore((state) => state.syncSubmodule);

Sources: CLAUDE.md, src/hooks/useAdminStore.ts

Frontend state management provides the necessary infrastructure to handle private admin operations securely and efficiently. By centralizing authentication and submodule synchronization, the system maintains high technical accuracy across all administrative modules.