# AGENTS.md

This file provides guidance for AI agents working in this repository.

## Project Overview

Simple Knowledge Base is a full-stack RAG (Retrieval-Augmented Generation) Q&A system built with React 19 + NestJS. It's a monorepo with Japanese/Chinese documentation but English code.

**Key Features:**
- Multi-model support (OpenAI-compatible APIs + Google Gemini native SDK)
- Dual processing modes: Fast (Tika text-only) and High-precision (Vision pipeline)
- User isolation with JWT authentication and per-user knowledge bases
- Hybrid search (vector + keyword) with Elasticsearch
- Multi-language interface (Japanese, Chinese, English)
- Streaming responses via Server-Sent Events (SSE)

## Build Commands

### Root Workspace
```bash
# Install all dependencies
yarn install

# Start both frontend and backend in dev mode
yarn dev
```

### Server (NestJS Backend) - Port 3001
```bash
cd server

# Build
yarn build

# Development server (watch mode)
yarn start:dev

# Format code
yarn format

# Lint code
yarn lint
```

### Web (React Frontend) - Port 13001
```bash
cd web

# Development server
yarn dev

# Build for production
yarn build
```

## Test Commands

### Server (Backend) - Jest Testing
```bash
cd server

# Run all tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run with coverage report
yarn test:cov

# Run single test file by name pattern
yarn test --testPathPattern=<test-name>

# Run single test by exact path
yarn test --testPathPattern=path/to/file.spec.ts

# Run e2e tests
yarn test:e2e

# Debug tests
yarn test:debug
```

**Examples of running single tests:**
```bash
# Run only auth service tests
yarn test --testPathPattern=auth.service.spec

# Run tests in specific file
yarn test src/chat/chat.service.spec.ts

# Run tests matching a pattern
yarn test --testPathPattern="user.*service"
```

**Note:** Frontend currently has no test framework configured.

## Code Style Guidelines

### Language Requirements
- **Comments**: English
- **Log messages**: English
- **Error messages**: Internationalized (i18n) - support Japanese/Chinese/English based on user's language preference

### Formatting
- **Prettier**: Single quotes, trailing commas enabled
- **ESLint**: TypeScript strict mode
- **TypeScript**: Avoid `any` types, use explicit typing

### Naming Conventions
- **Variables/Functions**: `camelCase` (e.g., `getUserData`, `processDocument`)
- **Classes/Interfaces/Types**: `PascalCase` (e.g., `UserService`, `UserDto`)
- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `MAX_FILE_SIZE`, `DEFAULT_TIMEOUT`)
- **Private members**: Prefix with underscore (e.g., `_privateMethod`)

### Import Organization
1. External libraries (npm packages)
2. Internal modules (project imports)
3. Relative imports (same directory)
4. Use absolute imports where configured

### Error Handling
```typescript
try {
  // Operation logic
} catch (error) {
  this.logger.error('Operation failed', error);
  throw new Error(this.i18n.t('errors.operationFailed'));
}
```

### Testing Guidelines
- Place test files as `*.spec.ts` in same directory as source
- Test file naming: `{serviceName}.spec.ts` or `{controllerName}.e2e-spec.ts`
- Use descriptive test names (describe blocks and it blocks)
- Mock external dependencies (APIs, databases)

## Project Architecture

### Directory Structure
```
auraAuraK/
├── web/                    # React frontend (Vite)
│   ├── components/         # UI components
│   ├── contexts/           # React Context providers
│   ├── services/           # API client services
│   └── utils/              # Utility functions
├── server/                 # NestJS backend
│   ├── src/
│   │   ├── ai/             # AI services (embedding, etc.)
│   │   ├── api/            # API module
│   │   ├── auth/           # JWT authentication
│   │   ├── chat/           # Chat/RAG module
│   │   ├── elasticsearch/  # Elasticsearch integration
│   │   ├── import-task/    # Import task management
│   │   ├── knowledge-base/ # Knowledge base management
│   │   ├── libreoffice/    # LibreOffice integration
│   │   ├── model-config/   # Model configuration management
│   │   ├── vision/         # Vision model integration
│   │   └── vision-pipeline/# Vision pipeline orchestration
│   ├── data/               # SQLite database storage
│   ├── uploads/            # Uploaded files storage
│   └── temp/               # Temporary files
├── docs/                   # Documentation (Japanese/Chinese)
├── nginx/                  # Nginx configuration
├── libreoffice-server/     # LibreOffice conversion service (Python/FastAPI)
└── docker-compose.yml      # Docker orchestration
```

### Key Concepts
- **Dual Processing Modes**: Fast (Tika) vs High-Precision (Vision Pipeline)
- **Multi-Model Support**: OpenAI-compatible APIs + Google Gemini
- **RAG System**: Hybrid search with Elasticsearch, SSE streaming responses
- **Authentication**: JWT-based user isolation
- **Database**: SQLite with TypeORM

## Reference

See `CLAUDE.md` for comprehensive project documentation and `docs/DEVELOPMENT_STANDARDS.md` for detailed coding standards.