State Management (Zustand & Jotai)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
State management in the bl1nk-skill-platform is designed to handle complex AI interactions, skill development workflows, and real-time application updates. The project utilizes a hybrid approach to state management, leveraging Zustand for global store-based state and Jotai for atomic, component-level state control. This architecture ensures that large-scale application data remains synchronized across the monorepo while maintaining high performance for interactive UI components.
The state management system specifically supports the 7-phase workflow of feature development, tracking project states from constitution through implementation. It handles everything from UI-side form validation and button loading states to persistent data models and AI-driven chat contexts.
Sources: plugins/spec-kit-skill/skills/spec-kit-skill/SKILL.md:1-15, apps/client/src/prompts/system_prompt.ts:13-30, specs/main/plan.md:12-25
Core Frameworks
The platform divides state responsibilities between two primary libraries to optimize for different data flow requirements.
Zustand Architecture
Zustand is used for high-level global state, particularly for stores that manage heavy data like chat histories and persistent application configurations. It facilitates the synchronization between the Electron-based client and the local data layer.
Jotai Atoms
Jotai is employed for atomic state management (atoms), which is ideal for independent UI states such as:
- App settings (key-value pairs)
- Ephemeral test messages
- Form validation states
- UI view toggles (e.g., refreshing the app preview)
Sources: Comprehensive.md:50-65, apps/client/src/prompts/system_prompt.ts:80-95, specs/main/plan.md:250-265
Data Flow and Transitions
The state management logic is tightly coupled with the development phases of the platform. State transitions often follow a linear progression as a user moves through requirements, design, and implementation.
The diagram shows how global stores manage the lifecycle of feature development phases while atoms handle the immediate UI feedback loop.
Sources: plugins/spec-kit-skill/skills/spec-kit-skill/SKILL.md:65-90, plugins/kiro-skill/skills/kiro-skill/SKILL.md:240-260
Key Implementation Areas
1. Chat and AI Integration State
Managing the state of AI interactions is critical. The system must track current thinking processes, system prompts, and tool usage across the session.
| State Component | Logic Location | Purpose |
|---|---|---|
| Thinking Process | system_prompt.ts | Tracks the internal analytical framework of the AI before response. |
| Command Execution | BUILD_SYSTEM_PREFIX | Toggles UI commands like Rebuild, Restart, and Refresh. |
| Dependency State | bl1nk-add-dependency | Manages the dynamic installation state of npm packages. |
Sources: apps/client/src/prompts/system_prompt.ts:7-25, apps/client/src/prompts/system_prompt.ts:80-100
2. Feature Development Phases
The state management system tracks the progression of a feature using file-based indicators and persistent stores.
Data Model and Persistence
The state managed by Zustand and Jotai eventually maps to the project's data layer, including SQLite databases and markdown-based memory files.
| Entity | State Type | Storage |
|---|---|---|
| SkillVersion | Persistent (Global) | SQLite / Prisma |
| App Settings | Atomic (Global) | Key-Value Store |
| Test Messages | Ephemeral (Atomic) | RAM |
| Constitution | Persistent (Phase) | .specify/memory/constitution.md |
Sources: Comprehensive.md:58-65, specs/main/plan.md:110-130
State Validation and Quality
The platform implements strict validation rules for state transitions, particularly during the "Clarify" and "Analyze" phases.
- Requirement Coverage: The state must verify that every requirement in the specification has a corresponding implementation task.
- Bilingual Parity: Documentation states must synchronize across English and Thai directories.
- Constitution Alignment: Technical decisions in the state must pass a "Constitution Check" before transitioning from Plan to Tasks.
Sources: plugins/spec-kit-skill/skills/spec-kit-skill/SKILL.md:250-280, specs/main/plan.md:60-85
Conclusion
State management in this platform is more than just UI synchronization; it is a governing system for the entire development lifecycle. By combining Zustand's store-centric approach with Jotai's atomicity, the application maintains a robust record of feature progression, AI context, and configuration integrity across its monorepo architecture.