diff --git a/.pi-map.index.md b/.pi-map.index.md index 52cb861..ba97793 100644 --- a/.pi-map.index.md +++ b/.pi-map.index.md @@ -16,7 +16,7 @@ dir: . Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and configuration package for a self-hosted project management platform with containerized deployment, SSO integration, and AI-assisted development workflows. +Infrastructure and deployment configuration for a self-hosted project management platform with containerized services, SSO integration, and AI agent development workflows. ## parent - ## children @@ -59,6 +59,9 @@ Infrastructure and configuration package for a self-hosted project management pl - tool-images index: tool-images/.pi-map.index.md map: tool-images/.pi-map.md +- uploads + index: uploads/.pi-map.index.md + map: uploads/.pi-map.md ## files - .env.example - .gitignore diff --git a/.pi-map.md b/.pi-map.md index 075b604..7924746 100644 --- a/.pi-map.md +++ b/.pi-map.md @@ -18,7 +18,7 @@ index: ./.pi-map.index.md Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker orchestration, environment templates, and development tooling. +Infrastructure and deployment configuration for a self-hosted project management platform with containerized services, SSO integration, and AI agent development workflows. ## files - .env.example | Provides a template of environment variables for configuring a Headquarter application with PostgreSQL, Redis, Authentik SSO, and Docker/Traefik deployment - .gitignore | Specifies files and directories for Git to ignore across a multi-language project with Python, Node, and custom tooling | dep: Git @@ -31,7 +31,7 @@ Infrastructure and deployment configuration for a self-hosted project management - progress.md | Tracks completed and remaining tasks for a backend-frontend code refactoring project organized in 7 phases - swap-pane | Empty file with no functionality ## arch -Containerized microservices architecture using Docker Compose with PostgreSQL/Redis data layer, Traefik reverse proxy for TLS/ingress, multi-stage build separation of API/backend and web frontend, and environment-driven configuration management. +Multi-service Docker Compose architecture with PostgreSQL/Redis data layer, Node/Python frontend/backend split, Traefik reverse proxy for TLS termination, and OpenSpec-driven AI agent orchestration with environment-based configuration management. ## tags docker, redis, git, application, postgresql, compose, traefik, project ## symbols diff --git a/apps/.pi-map.index.md b/apps/.pi-map.index.md index a65d3ec..9d5e74a 100644 --- a/apps/.pi-map.index.md +++ b/apps/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps ## role -Contains the main deployable application entry points and top-level executable modules for the project. +Contains the main deployable application entry points and top-level configurations for the project. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/apps/.pi-map.md b/apps/.pi-map.md index f37f96d..597eba2 100644 --- a/apps/.pi-map.md +++ b/apps/.pi-map.md @@ -4,10 +4,10 @@ dir: apps index: apps/.pi-map.index.md ## role -Contains the main deployable application entry points and top-level configuration for the project. +Contains the main deployable application entry points and top-level configurations for the project. ## files ## arch -Monorepo-style directory structure with separate application modules, typically following a microservices or modular monolith pattern where each sub-directory represents an independent runnable service or app. +Monorepo-style directory structure typically housing multiple independent applications that share common libraries or modules, each with its own configuration and dependencies. ## tags - ## symbols diff --git a/apps/web/.pi-map.index.md b/apps/web/.pi-map.index.md index 44a1bb2..0cfd285 100644 --- a/apps/web/.pi-map.index.md +++ b/apps/web/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web ## role -Frontend web application providing a React-based UI with code editing, terminal, and routing capabilities for the "headquarter" project. +Frontend web application serving as the browser-based UI for the project, built with React/Vite/TypeScript and deployed via nginx. ## parent index: apps/.pi-map.index.md map: apps/.pi-map.md diff --git a/apps/web/.pi-map.md b/apps/web/.pi-map.md index f81e3a7..4e9fdae 100644 --- a/apps/web/.pi-map.md +++ b/apps/web/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web index: apps/web/.pi-map.index.md ## role -Frontend web application providing a React-based UI with code editing, terminal, and routing capabilities for the "headquarter" project. +Frontend web application serving as the browser-based UI for the project, built with React/Vite/TypeScript and deployed via nginx. ## files - .env.example | Template file defining example environment variables for frontend API and application URL configuration - .eslintrc.cjs | Configures ESLint for a TypeScript browser project with modern ECMAScript module support | dep: @typescript-eslint/parser, @typescript-eslint/eslint-plugin, eslint @@ -16,7 +16,7 @@ Frontend web application providing a React-based UI with code editing, terminal, - tsconfig.json | TypeScript configuration file for a React project using Vite with modern ES2020 target and bundler module resolution | dep: typescript, react, vite - vite.config.ts | Configures Vite build tool for a React project with custom dev server port and Vitest test settings. | dep: vite, @vitejs/plugin-react ## arch -Modern React SPA built with Vite and TypeScript, containerized via multi-stage Docker with nginx serving, featuring client-side routing and optimized static asset delivery. +Modern SPA architecture using Vite for bundling, React for UI, TypeScript for type safety, with containerized nginx deployment and environment-driven configuration. ## tags react, eslint, vite, typescript, dom, application, nginx, web ## symbols diff --git a/apps/web/src/.pi-map.index.md b/apps/web/src/.pi-map.index.md index c72f1a0..4ebffb3 100644 --- a/apps/web/src/.pi-map.index.md +++ b/apps/web/src/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src ## role -Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions. +Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend. ## parent index: apps/web/.pi-map.index.md map: apps/web/.pi-map.md diff --git a/apps/web/src/.pi-map.md b/apps/web/src/.pi-map.md index 704a13f..6b1e291 100644 --- a/apps/web/src/.pi-map.md +++ b/apps/web/src/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/web/src index: apps/web/src/.pi-map.index.md ## role -Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions. +Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend. ## files - main.tsx | Bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom - router.tsx | Defines the React Router configuration for a web application with protected routes, nested layouts, and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage - types.ts | Defines TypeScript type definitions for user sessions, projects, repositories, and workspaces in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos ## arch -Provider pattern wrapping React Router with nested route layouts, protected route guards via authentication/session providers, and centralized TypeScript type definitions for domain models. +Layered architecture with provider composition pattern for cross-cutting concerns (auth, routing, sessions), declarative route configuration with nested layouts and route guards, and centralized TypeScript domain modeling. ## tags pages, styles, css, router, react, session, dom, project ## symbols diff --git a/apps/web/src/components/.pi-map.index.md b/apps/web/src/components/.pi-map.index.md index 1ce81e5..42d604a 100644 --- a/apps/web/src/components/.pi-map.index.md +++ b/apps/web/src/components/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components ## role -Reusable React UI components and authentication guards for the web application's frontend interface. +Provides reusable, accessible React UI components and utilities for the web application including layout shells, data display states, icon system, code editing, routing guards, and toast notification infrastructure. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md @@ -15,6 +15,7 @@ map: apps/web/src/.pi-map.md - code-editor.tsx - data-states.tsx - icon.tsx +- loading-overlay.tsx - protected-route.test.tsx - protected-route.tsx - syntax-highlighter.tsx diff --git a/apps/web/src/components/.pi-map.md b/apps/web/src/components/.pi-map.md index 99346c1..68984f2 100644 --- a/apps/web/src/components/.pi-map.md +++ b/apps/web/src/components/.pi-map.md @@ -4,22 +4,24 @@ dir: apps/web/src/components index: apps/web/src/components/.pi-map.index.md ## role -Reusable React UI components and authentication guards for the web application's frontend interface. +Provides reusable, accessible React UI components and utilities for the web application including layout shells, data display states, icon system, code editing, routing guards, and toast notification infrastructure. ## files -- app-shell.tsx | Renders the main application shell layout with navigation, session management, and responsive mobile/desktop views for a React Router-based app. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ../state/session-operations, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./features/session/session-progress-panel, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons +- app-shell.tsx | Renders the main application shell layout with navigation, session management, and responsive mobile/desktop views for a React Router-based app. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons - code-editor.tsx | A React component that renders a syntax-highlighted code editor with line numbers using react-simple-code-editor. | exp: CodeEditor | dep: react, react-simple-code-editor, ../utils/language - data-states.tsx | Provides reusable React components for displaying loading, error, and empty data states in a UI. | exp: LoadingState, ErrorState, EmptyState | dep: ./icon, icon - icon.tsx | Provides a centralized, type-safe React icon component that maps semantic names to Phosphor icons with configurable size, weight, color, and accessibility attributes. | exp: IconName, IconProps, Icon | dep: react, @phosphor-icons/react +- loading-overlay.tsx | Renders an accessible loading overlay with optional label that conditionally displays based on visibility prop | exp: func:LoadingOverlay({ visible, label }: LoadingOverlayProps) | dep: ./icon, icon - protected-route.test.tsx | Tests a ProtectedRoute component that guards content based on authentication state | dep: @testing-library/react, react-router-dom, vitest, ./protected-route - protected-route.tsx | Conditionally renders children or redirects to login based on authentication state | exp: ProtectedRoute | dep: react-router-dom, ../state/auth - syntax-highlighter.tsx | Renders syntax-highlighted code blocks with optional line numbers and copy-to-clipboard functionality | exp: SyntaxHighlighter | dep: react, ./icon, ../utils/language, React, icon, language (utils) - toast-rules.test.ts | Unit tests for mapping instance events to toast notification categories and severities | dep: vitest, ./toast-rules, ../types/events - toast-rules.ts | Maps instance events to toast notifications with deduplication logic to prevent spam | exp: func:mapEventToCategory(event: InstanceEventPayload) → string, call:event.event.startsWith, func:mapEventToSeverity(event: InstanceEventPayload) → "info" | "warning" | "error" | "success", func:handleEventToast(event: InstanceEventPayload) → void, call:shouldShowToast, call:toast.info, call:toast.success, call:toast.warning, call:toast.error, func:clearToastDedup() → void, call:lastToastTime.clear | dep: ../state/toast, ../types/events, toast state module, InstanceEventPayload type ## arch -Component-based React architecture using functional components with hooks, centralized type-safe utilities (icons, data states), composition patterns for layout (app-shell), and higher-order route protection for auth gating. +Component-based architecture with functional React patterns, custom hooks for state management, utility modules for cross-cutting concerns (icons, toasts), and test co-location with implementation files. ## tags -toast, state, react, icon, code, event, editor, protected +toast, icon, react, state, code, loading, event, editor ## symbols +- LoadingOverlay - mapEventToCategory - mapEventToSeverity - handleEventToast @@ -27,7 +29,6 @@ toast, state, react, icon, code, event, editor, protected - AppShell - CodeEditor - LoadingState -- ErrorState ## workflows - change components behavior read: app-shell.tsx, code-editor.tsx, data-states.tsx diff --git a/apps/web/src/components/features/.pi-map.index.md b/apps/web/src/components/features/.pi-map.index.md index 7fef5bd..482f345 100644 --- a/apps/web/src/components/features/.pi-map.index.md +++ b/apps/web/src/components/features/.pi-map.index.md @@ -1,52 +1,52 @@ -# apps/web/src/components/features (index) -dir: apps/web/src/components/features +# features (index) +dir: features ## role -Contains reusable UI components that implement specific business features and user-facing functionality across the web application. +Contains modular, feature-based components that encapsulate specific domain functionality or user-facing capabilities within the project. ## parent -index: apps/web/src/components/.pi-map.index.md -map: apps/web/src/components/.pi-map.md +index: ./.pi-map.index.md +map: ./.pi-map.md ## children -- apps/web/src/components/features/config-profiles - index: apps/web/src/components/features/config-profiles/.pi-map.index.md - map: apps/web/src/components/features/config-profiles/.pi-map.md -- apps/web/src/components/features/git - index: apps/web/src/components/features/git/.pi-map.index.md - map: apps/web/src/components/features/git/.pi-map.md -- apps/web/src/components/features/mobile - index: apps/web/src/components/features/mobile/.pi-map.index.md - map: apps/web/src/components/features/mobile/.pi-map.md -- apps/web/src/components/features/notification - index: apps/web/src/components/features/notification/.pi-map.index.md - map: apps/web/src/components/features/notification/.pi-map.md -- apps/web/src/components/features/project - index: apps/web/src/components/features/project/.pi-map.index.md - map: apps/web/src/components/features/project/.pi-map.md -- apps/web/src/components/features/session - index: apps/web/src/components/features/session/.pi-map.index.md - map: apps/web/src/components/features/session/.pi-map.md -- apps/web/src/components/features/settings - index: apps/web/src/components/features/settings/.pi-map.index.md - map: apps/web/src/components/features/settings/.pi-map.md -- apps/web/src/components/features/ssh-keys - index: apps/web/src/components/features/ssh-keys/.pi-map.index.md - map: apps/web/src/components/features/ssh-keys/.pi-map.md -- apps/web/src/components/features/terminal - index: apps/web/src/components/features/terminal/.pi-map.index.md - map: apps/web/src/components/features/terminal/.pi-map.md -- apps/web/src/components/features/tool - index: apps/web/src/components/features/tool/.pi-map.index.md - map: apps/web/src/components/features/tool/.pi-map.md -- apps/web/src/components/features/tool-workshop - index: apps/web/src/components/features/tool-workshop/.pi-map.index.md - map: apps/web/src/components/features/tool-workshop/.pi-map.md -- apps/web/src/components/features/workspace - index: apps/web/src/components/features/workspace/.pi-map.index.md - map: apps/web/src/components/features/workspace/.pi-map.md +- features/config-profiles + index: features/config-profiles/.pi-map.index.md + map: features/config-profiles/.pi-map.md +- features/git + index: features/git/.pi-map.index.md + map: features/git/.pi-map.md +- features/mobile + index: features/mobile/.pi-map.index.md + map: features/mobile/.pi-map.md +- features/notification + index: features/notification/.pi-map.index.md + map: features/notification/.pi-map.md +- features/project + index: features/project/.pi-map.index.md + map: features/project/.pi-map.md +- features/session + index: features/session/.pi-map.index.md + map: features/session/.pi-map.md +- features/settings + index: features/settings/.pi-map.index.md + map: features/settings/.pi-map.md +- features/ssh-keys + index: features/ssh-keys/.pi-map.index.md + map: features/ssh-keys/.pi-map.md +- features/terminal + index: features/terminal/.pi-map.index.md + map: features/terminal/.pi-map.md +- features/tool + index: features/tool/.pi-map.index.md + map: features/tool/.pi-map.md +- features/tool-workshop + index: features/tool-workshop/.pi-map.index.md + map: features/tool-workshop/.pi-map.md +- features/workspace + index: features/workspace/.pi-map.index.md + map: features/workspace/.pi-map.md ## files ## links -index: apps/web/src/components/features/.pi-map.index.md -map: apps/web/src/components/features/.pi-map.md +index: features/.pi-map.index.md +map: features/.pi-map.md ## workflows - ## dirty diff --git a/apps/web/src/components/features/.pi-map.md b/apps/web/src/components/features/.pi-map.md index c024d0a..ee6baf0 100644 --- a/apps/web/src/components/features/.pi-map.md +++ b/apps/web/src/components/features/.pi-map.md @@ -1,13 +1,13 @@ -# apps/web/src/components/features -dir: apps/web/src/components/features +# features +dir: features -index: apps/web/src/components/features/.pi-map.index.md +index: features/.pi-map.index.md ## role -Contains reusable UI components that implement specific business features and user-facing functionality across the web application. +Contains modular, feature-based components that encapsulate specific domain functionality or user-facing capabilities within the project. ## files ## arch -Feature-based component organization with domain-specific groupings, likely using composition patterns, container/presentational separation, and integration with hooks/state management for feature logic. +Feature-based modular architecture with self-contained, cohesive units that likely combine related components, logic, and assets to support vertical slicing of application functionality. ## tags - ## symbols diff --git a/apps/web/src/components/features/session/.pi-map.index.md b/apps/web/src/components/features/session/.pi-map.index.md index 4809a75..e40601a 100644 --- a/apps/web/src/components/features/session/.pi-map.index.md +++ b/apps/web/src/components/features/session/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/components/features/session ## role -Provides UI components for managing development sessions including creation, listing, monitoring progress, and interacting with individual sessions. +Provides UI components for managing development sessions including creation, listing, and interacting with individual sessions. ## parent index: apps/web/src/components/features/.pi-map.index.md map: apps/web/src/components/features/.pi-map.md @@ -12,7 +12,6 @@ map: apps/web/src/components/features/.pi-map.md - create-session-form.tsx - session-card.tsx - session-list.tsx -- session-progress-panel.tsx ## links index: apps/web/src/components/features/session/.pi-map.index.md map: apps/web/src/components/features/session/.pi-map.md diff --git a/apps/web/src/components/features/session/.pi-map.md b/apps/web/src/components/features/session/.pi-map.md index d3b1133..b39ed40 100644 --- a/apps/web/src/components/features/session/.pi-map.md +++ b/apps/web/src/components/features/session/.pi-map.md @@ -4,20 +4,18 @@ dir: apps/web/src/components/features/session index: apps/web/src/components/features/session/.pi-map.index.md ## role -Provides UI components for managing development sessions including creation, listing, monitoring progress, and interacting with individual sessions. +Provides UI components for managing development sessions including creation, listing, and interacting with individual sessions. ## files - create-session-form.tsx | A React form component for creating and starting a new development session with configurable project, repository, workspace, tool type, config profile, and SSH key options. | exp: CreateSessionForm | dep: react, ../../icon, ../../../api/sessions, ../../../types, ../../../api/git-repositories, ../../../api/tool-types, ../../../api/ssh-keys, ../../../api/config-profiles, ../../../api/workspaces, ../../../types/workspace, icon, sessions API, git-repositories API, tool-types API, ssh-keys API, config-profiles API, workspaces API, types - session-card.tsx | Renders a card component displaying session information with status badges, inline rename editing, action buttons, and responsive mobile/desktop layouts including a dropdown options menu and mobile action sheet. | exp: SessionCardProps, func:SessionCard({ session, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, isBusy = false, tunnelHealth = null, }: SessionCardProps), call:useState, call:useRef, call:useMobileViewport, call:session.tool_type_interfaces?.includes, call:[ "running", "building", "starting", "probing", "pending", "unhealthy", ].includes, call:useEffect, call:optionsRef.current.contains, call:setOptionsOpen, call:document.addEventListener, call:document.removeEventListener, call:window.confirm, call:onDelete, call:setEditName, call:onRename, call:setIsEditingName, call:editName.trim, call:onOpen, call:new Date(session.created_at).toLocaleString, call:setShowActionSheet, call:onStart, call:onStop, call:onRecreateTunnel | dep: react, ../../../api/sessions, ../../icon, ../../../hooks/use-mobile-viewport, ../mobile/mobile-action-sheet - session-list.tsx | Renders a list of sessions grouped by active/recent status or as a flat grid, delegating to SessionCard for individual session display. | exp: SessionListProps, func:SessionList({ sessions, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, actionBusyId = null, tunnelHealth = {}, showGrouping = true, activeTitle = "Active Sessions", recentTitle = "Recent Sessions", maxRecent = 5, emptyMessage = "No sessions", }: SessionListProps), call:sessions.filter, call:activeStatuses.includes, call:sessions .filter((s) => recentStatuses.includes(s.status)) .slice, call:recentStatuses.includes, call:sessions.map, call:activeSessions.map, call:recentSessions.map | dep: ../../../api/sessions, ./session-card, Session, SessionCard, InstanceHealth -- session-progress-panel.tsx | Renders a panel displaying active and recently completed session operations with step-by-step progress indicators and dismissible notifications. | exp: func:SessionProgressPanel(), call:useSessionOperations, call:useEventContext, call:useEffect, call:updateOperationFromEvent, call:operations.filter, call:Date.now, call:visibleOperations.map, call:dismissOperation | dep: react, ../../../state/session-operations, ../../../state/events, ../../icon, useSessionOperations, useEventContext, Icon ## arch -Feature-based component architecture with compound component pattern (SessionCard/SessionList/SessionProgressPanel), controlled forms with validation, optimistic UI updates for inline editing, responsive design with mobile/desktop layout variants, and compound action menus using dropdowns/sheets. +Feature-based component architecture with compound component pattern (SessionCard/SessionList), controlled forms with validation, optimistic UI updates for inline editing, responsive design with mobile/desktop layout variants, and compound action menus using dropdowns/sheets. ## tags session, call:use, call:on, api, card, call:set, event, mobile ## symbols - SessionCard - SessionList -- SessionProgressPanel - CreateSessionForm - SessionCardProps - call:useState diff --git a/apps/web/src/state/.pi-map.index.md b/apps/web/src/state/.pi-map.index.md index ebcc25a..b860286 100644 --- a/apps/web/src/state/.pi-map.index.md +++ b/apps/web/src/state/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/state ## role -Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback. +Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, and user feedback. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md @@ -12,7 +12,6 @@ map: apps/web/src/.pi-map.md - auth.tsx - events.tsx - notifications.tsx -- session-operations.tsx - sessions.tsx - toast.tsx ## links diff --git a/apps/web/src/state/.pi-map.md b/apps/web/src/state/.pi-map.md index a6b7f5f..25e99b8 100644 --- a/apps/web/src/state/.pi-map.md +++ b/apps/web/src/state/.pi-map.md @@ -4,18 +4,17 @@ dir: apps/web/src/state index: apps/web/src/state/.pi-map.index.md ## role -Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback. +Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, and user feedback. ## files - auth.tsx | Provides React authentication context for managing user session state with login status, user data, and session refresh/logout operations. | exp: AuthProvider, useAuth | dep: react, ../api/client, ../types - events.tsx | Creates a React context provider for real-time event data with connection status and reconnection tracking | exp: func:EventProvider({ children }: { children: React.ReactNode }), call:useEvents, call:useMemo, func:useEventContext(), call:useContext | dep: react, ../hooks/use-events, ../types/events - notifications.tsx | Provides a React context provider that manages notification state with optimistic updates, polling, and dropdown-aware fetching. | exp: NotificationContextValue, NotificationContext, func:NotificationProvider({ children, }: { children: React.ReactNode; }), call:useState, call:useRef, call:useCallback, call:getUnreadCount, call:setUnreadCount, call:clearInterval, call:console.error, call:setIsLoading, call:getNotifications, call:setNotifications, call:fetchUnreadCount, call:setInterval, call:fetchList, call:useEffect, call:stopPolling, call:startPolling, call:document.addEventListener, call:document.removeEventListener, call:currentNotifications.find, call:currentNotifications.map, call:new Date().toISOString, call:Math.max, call:setError, call:markNotificationRead, call:markAllNotificationsRead, call:currentNotifications.filter, call:dismissNotification, call:clearAllNotifications | dep: react, ../api/notifications, React -- session-operations.tsx | Manages a React context provider for tracking asynchronous instance operations (create, start, stop, etc.) with status updates from event payloads. | exp: OperationType, OperationStatus, Operation, SessionOperationsContextType, SessionOperationsProvider, useSessionOperations | dep: react, ../types/events - sessions.tsx | Provides a React context that manages user sessions state with server polling, local CRUD operations, and loading/error handling. | exp: SessionsContextType, SessionsProvider, useSessions | dep: react, ../api/sessions - toast.tsx | Implements a React toast notification system with context-based state management, auto-dismiss timers, and imperative API shortcuts. | exp: ToastSeverity, ToastItem, toast, func:ToastProvider({ children }: { children: React.ReactNode }), call:useState, call:useRef, call:useCallback, call:setToasts, call:prev.filter, call:timersRef.current.get, call:clearTimeout, call:timersRef.current.delete, call:Date.now, call:setTimeout, call:removeToast, call:timersRef.current.set, call:useEffect, call:addToast, func:useToast(), call:useContext, raise:Error | dep: react, React ## arch -React Context API pattern with separate providers per domain, combining optimistic updates, server polling, event-driven state synchronization, and imperative APIs for cross-cutting concerns like toast notifications. +React Context API pattern with separate providers per domain, combining optimistic updates, server polling, event-driven state synchronization, and imperative APIs for cross-cutting concerns. ## tags -call:use, context, toast, provider, react, call:set, notification, operations +call:use, context, toast, provider, react, call:set, notification ## symbols - EventProvider - useEventContext @@ -24,7 +23,6 @@ call:use, context, toast, provider, react, call:set, notification, operations - useToast - AuthProvider - useAuth -- call:useEvents ## workflows - change state behavior read: auth.tsx, events.tsx, notifications.tsx