KnowledgeBase/AGENTS.md

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

# Install all dependencies
yarn install

# Start both frontend and backend in dev mode
yarn dev

Server (NestJS Backend) - Port 3001

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

cd web

# Development server
yarn dev

# Build for production
yarn build

Test Commands

Server (Backend) - Jest Testing

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:

# 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

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)

UX & UI Guidelines

Notifications & Confirmations

• No Native Dialogs: Do not use native alert(), confirm(), or prompt().
• Toast Notifications: Use the ToastContext (useToast hook) for all notifications (success, error, info).
• Toast Confirmations: Use ConfirmContext (useConfirm hook) for user confirmations. Confirmations should follow modern "toast-style" aesthetics (non-blocking, highly rounded, simplified UI) and be positioned centrally or as toasts depending on the context for a smooth experience.

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.