DOCSEARCHbyAlgolia
Submit Docs

Chikaima Documentation

website·Indexed 30 days ago

https://chikaima.com/

Technical documentation for Chikaima v2.0.0, featuring a Next.js application structure with route handlers for the /api/v1 surface. The system utilizes an embedded SQLite database with sqlite-vec for asset chunk retrieval and supports deployment via Docker Compose.

Tokens
15.4K
Snippets
55
Records
143
Agent score
48%

What's inside Chikaima

  1. Frontend Tech Stack Overview

    The application is built as a unified Next.js project (as of v2.0.0, the frontend and backend were merged into the repository root). The core stack consists of:

    • Next.js App Router (v16)
    • React 19
    • TypeScript
    • TanStack Query (for server state)
    • React Hook Form & Zod (for form handling and validation)
    • Zustand (for client-side state management)
    • Tailwind CSS v4

  2. Troubleshoot SQLite and sqlite-vec errors

    The app loads sqlite-vec into the better-sqlite3 connection at startup (core/db/client.ts). If vector search fails:

    • Architecture Mismatch: Ensure the sqlite-vec native binding matches your platform/architecture (most common on local dev machines; the official Docker image is pre-configured).
    • Dimension Mismatch: Ensure CHIKAIMA_EMBEDDING_DIMENSION has not changed since the asset_chunk_vectors table was created. The vector width is fixed at migration time (default float[384]), and mismatches will cause errors during insertion.

  3. Chikaima High-Level Architecture Overview

    As of v2.0.0, Chikaima is a single Next.js application. It has collapsed from a two-service (Next.js + FastAPI) stack into a unified TypeScript codebase. There is no separate backend process, database server, or message broker required. The architecture consists of a Next.js App Router UI, API Route Handlers (/api/v1/*), a framework-independent core/** service layer, an embedded SQLite database (via better-sqlite3 and sqlite-vec), and an in-process background worker.

  4. Manage AI Providers and Adapters

    The provider architecture decouples chat, embeddings, and transcription flows from specific vendors. It consists of a provider catalog, model metadata, a factory for adapter selection, and specific adapters (e.g., OpenAI, Anthropic, Gemini, Ollama). OpenAI-compatible providers reuse the OpenAI adapter shape.

  5. Implement Chat capabilities in Chikaima

    The chat system supports the following core functionalities: conversation creation and listing, message streaming via Server-Sent Events (SSE), model selection, RAG-assisted responses with citations sourced from asset chunks, and vision-aware model switching (when configured).

  6. Chikaima Backend Tech Stack Overview

    As of v2.0.0, Chikaima uses a unified Next.js application for both the UI and backend logic. The architecture is split between Next.js Route Handlers for the API layer and a framework-independent service layer in core/** to ensure testability and separation of concerns.
    - Framework: Next.js (App Router)
- Language: TypeScript
- ORM: Drizzle ORM
- Database: better-sqlite3 + sqlite-vec
- Auth: jose (JWT)
- Package Manager: pnpm
- Testing: Node's built-in test runner (node --test)

  7. Frontend Component and Data Flow Architecture

    Components are organized by domain to match the API surface (e.g., components/chat, components/providers, components/assets).

    Data Flow Pattern:

    1. Auth tokens are retrieved from Zustand stores (store/auth-store.ts, store/admin-auth-store.ts).
    2. TanStack Query fetches data from the internal /api/v1/* route handlers.
    3. Domain components perform mutations and renders via services/api.ts.
    4. Invalidation triggers refreshes of dependent views.

    Since the UI and API are served by the same Next.js process, requests to NEXT_PUBLIC_API_BASE_URL (defaulting to /api/v1) are same-origin, eliminating the need for cross-service proxies.

  8. Resolve SQLite and sqlite-vec errors

    The application loads sqlite-vec into the better-sqlite3 connection at startup (core/db/client.ts). If vector search fails:

    • Architecture Mismatch: Ensure the sqlite-vec native binding matches your platform/architecture (common on non-standard local dev machines; official Docker images are pre-configured).
    • Dimension Mismatch: Ensure CHIKAIMA_EMBEDDING_DIMENSION has not changed since the asset_chunk_vectors table was created. The vector width (default float[384]) is fixed at migration time; mismatches will cause errors during insertion.

  9. Understand Chikaima's database architecture

    As of v2.0.0, Chikaima uses an embedded SQLite database as its primary store, replacing the previous PostgreSQL + pgvector setup. It utilizes better-sqlite3 as the driver and sqlite-vec as a SQLite extension for vector retrieval over asset chunks. There is no external database server to provision.

  10. Follow chikaima repository conventions

    To maintain project architecture, adhere to the following conventions:

    • Dependency Management: Use pnpm exclusively.
    • Core Logic: Code in core/** must remain framework-independent and cannot import from next (enforced by ESLint).
    • API Design: Route handlers in app/api/v1/** should be thin: parse requests, call core/** logic, and shape the response.
    • Testing: Unit tests use Node's built-in test runner and are compiled from TypeScript via tsc -p tsconfig.test.json.

  11. Chikaima Technical Stack Overview

    Chikaima is designed for media-heavy retrieval and chat. Its technical architecture consists of:

    • Frontend/Backend: Next.js with embedded SQLite (no separate backend required).
    • Supported LLMs: OpenAI, Anthropic, Gemini, and Ollama.
    • Supported Media: Documents, audio, and video.

  12. Understand Chikaima Chat capabilities

    The Chat feature supports conversation creation and listing, message streaming via Server-Sent Events (SSE), model selection, and RAG-assisted responses. It includes citations sourced from asset chunks and supports vision-aware model switching when configured.