docs/project-structure.md

# Project Structure

## Directory Layout

- **`client/`**: Frontend React application
  - **`components/`**: Feature-based UI components
    - **`App/`**: Main application component with error boundaries
    - **`AiResponse/`**: AI response display and chat interface components
    - **`Analytics/`**: Search analytics and statistics components
    - **`Logs/`**: Application logging and debug modal components
    - **`Pages/`**: Route-level page components
      - **`Main/`**: Main search interface with menu and settings
    - **`Search/`**: Search functionality components
      - **`Form/`**: Search input and form components
      - **`History/`**: Search history and saved searches
      - **`Results/`**: Search results display (textual and graphical)
    - **`Settings/`**: Application settings and configuration
  - **`hooks/`**: Custom React hooks
  - **`modules/`**: Core business logic (PubSub stores, search services, database layers)
  - **`public/`**: Static assets
- **`server/`**: Server hooks for search endpoints, caching, compression, CORS, and API validation
- **`shared/`**: Utilities shared between client and server
- **`vite.config.ts`**: Build and server configuration with environment-driven feature flags

## Component Organization

Components are organized by feature domain. Each component folder contains:
- Component implementation
- Related styles
- Custom hooks
- Utility functions
- Tests

This self-contained structure makes it easy for agents to understand and modify components without navigating across the codebase.

## Key Modules Reference

The `client/modules/` directory contains core business logic organized by domain:

| Module | Purpose |
|--------|---------|
| `pubSub.ts` | All PubSub channels for state management |
| `search.ts` | Search orchestration, caching, and reranking |
| `textGeneration.ts` | AI response generation and chat handling |
| `textGenerationWith*.ts` | Provider-specific inference implementations (WebLLM, Wllama, OpenAI, Horde, Internal API) |
| `history.ts` | IndexedDB persistence for searches and chat |
| `settings.ts` | Default settings and inference type definitions |
| `followUpQuestions.ts` | Generates contextual follow-up questions |
| `relatedSearchQuery.ts` | Creates related search queries from conversation |
| `querySuggestions.ts` | Query suggestion UI data management |
| `webGpu.ts` | WebGPU availability and F16 shader detection |
| `wllama.ts` | Wllama model configuration and management |
| `accessKey.ts` | Access key validation and storage |
| `searchTokenHash.ts` | CSRF protection token generation |
| `parentWindow.ts` | PostMessage API for parent window embedding |
| `logEntries.ts` | Application logging with unique IDs |
| `appInfo.ts` | Application metadata and version info |
| `keyboard.ts` | Keyboard shortcut handling |
| `systemPrompt.ts` | System prompt templates |
| `stringFormatters.ts` | Text formatting utilities |
| `types.ts` | Shared TypeScript type definitions |

## Related Topics

- **Overview**: `docs/overview.md` - System architecture and data flow
- **UI Components**: `docs/ui-components.md` - Component architecture and PubSub patterns
- **Quick Start**: `docs/quick-start.md` - Installation and setup