Repository navigation
Architecture
PsyMind.AI follows a modular service-oriented architecture. Each layer has a single responsibility and can be replaced or migrated independently.
src/
├── services/
│ ├── api/
│ │ ├── geminiClient.js # Google Gemini API client
│ │ ├── errorHandler.js # Centralized error parsing
│ │ └── retryHandler.js # Exponential backoff retry logic
│ ├── chat/
│ │ ├── chatService.js # Core chat orchestration & Meta-Insight AI agent
│ │ └── messageFormatter.js # Message normalization for Gemini
│ ├── analytics/
│ │ └── telemetry.js # On-device metric calculus parsing focus and usage counts
│ ├── tools/
│ │ ├── pomodoroService.js # AI tips for focus/break cycles
│ │ ├── moodService.js # Mood history analysis
│ │ └── reflectionService.js # Reflection prompt generation
│ ├── storage/
│ │ ├── chatStorage.js # Chat persistence (localStorage)
│ │ └── settingsStorage.js # User settings persistence
│ ├── prompts/
│ │ └── systemPrompts.js # System prompt logic and dynamic Local Storage context ingestion
│ ├── adapters/ # Pluggable storage adapters
│ └── index.js # Public service interface
├── utils/
│ ├── notifications.js # Browser notifications and sounds
│ ├── textStreaming.js # Typewriter streaming effect
│ └── themeTransition.js # Animated theme switching
├── context/ # React context providers
├── components/ # UI components
└── pages/ # Route-level pages
geminiClient.js — Thin wrapper around @google/genai.
import { GeminiClient } from './services/api/geminiClient';
const client = new GeminiClient(apiKey);
await client.generateContent({ model, contents });errorHandler.js — Normalizes API errors into typed responses.
import { parseError, createErrorResponse, ERROR_TYPES } from './services/api/errorHandler';retryHandler.js — Retries failed requests with configurable backoff.
import { withRetry } from './services/api/retryHandler';
await withRetry(() => apiCall(), retries, delay);chatService.js — Orchestrates message sending, history management, and title generation.
import { sendMessage, generateTitle, isConfigured } from './services/chat/chatService';messageFormatter.js — Converts internal message format to Gemini's contents schema.
import { formatHistoryForGemini, createUserMessage, createAIMessage } from './services/chat/messageFormatter';chatStorage.js
import { loadChats, saveChats, createChat, updateChat } from './services/storage/chatStorage';settingsStorage.js
import { loadSetting, saveSetting, loadBooleanSetting } from './services/storage/settingsStorage';import { generatePomodoroTip } from './services/tools/pomodoroService';
import { generateMoodInsight } from './services/tools/moodService';
import { generateReflection, generateReflectionAnalysis } from './services/tools/reflectionService';telemetry.js — Edgeside metrics computation gathering local behavioral usage patterns dynamically mapped by psymind_telemetry_optin.
import { Telemetry, TelemetryEngine } from './services/analytics/telemetry';textStreaming.js — Streams AI responses character-by-character with reduced-motion support.
import { TextStreamer } from './utils/textStreaming';
const streamer = new TextStreamer(text, onChunk, onComplete, reducedMotion);
streamer.start();themeTransition.js
import { animateThemeTransition } from './utils/themeTransition';
await animateThemeTransition(event, callback, reducedMotion);notifications.js
import { playNotificationSound, showNotification, requestNotificationPermission } from './utils/notifications';The chat pipeline automatically augments the system prompt with metadata from local tools, generating highly personalized yet strictly local edge-state awareness.
User Input → ChatContext → chatService → systemPrompts (Context Injection) → geminiClient → Gemini API
↓ ↓
chatStorage ← messageFormatter ← errorHandler
A secondary execution loop decoupled from the interactive UI. Evaluates multi-tool activity (Pomodoros, Mood logs) to synthesize patterns quietly in the background without halting the main rendering thread.
Dashboard Trigger → generateMetaInsight → systemPrompts (Cross-Reference Rule) → geminiClient
↓
telemetry.js (Aggregates Focus vs Moods)
User Action → ThemeContext → settingsStorage → localStorage
↓
themeTransition
All storage modules accept a custom adapter, enabling migration from localStorage to any backend:
import { StorageAdapter } from './services';
class DatabaseAdapter extends StorageAdapter {
async get(key) { return await db.find(key); }
async set(key, value) { return await db.save(key, value); }
}
loadChats(new DatabaseAdapter());See MIGRATION_GUIDE.md for instructions on extracting individual modules into other projects.