Vaessl/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Vaessl is an AI-powered integration bridge that accepts user text/image inputs, processes them through an LLM pipeline (via LiteLLM), and exports structured data to management systems (Homebox, WikiJS). The backend uses a provider pattern for extensibility, and the frontend is in early scaffolding stage.

Commands

Backend (Spring Boot + Gradle, inside backend/)

./gradlew build           # compile and package
./gradlew test            # run all tests
./gradlew test --tests com.vaessl.app.connection.ConnectionServiceTest  # single test class

Frontend (React + Vite, inside frontend/)

npm run dev       # start dev server
npm run build     # TypeScript check + Vite build
npm run lint      # ESLint
npm run test      # Vitest watch mode
npm run test:ui   # Vitest visual dashboard

Environment

Copy .env.local (not committed) into backend/ with:

• DB_URL, DB_TEST_URL, DB_USERNAME, DB_PASSWORD — PostgreSQL (test container on port 5434)
• OPENAI_KEY, OPENAI_BASE_URL — LiteLLM gateway (provider-agnostic, configured for gpt-4o-mini)

Architecture

Backend (backend/src/main/java/com/vaessl/app/)

Three main modules:

connection/ — core business logic

• ConnectionProvider interface: each integrated app (Homebox, WikiJS) implements login() and declares its ServiceType
• ConnectionService: auto-discovers providers via Spring injection, dispatches login by ServiceType
• Entity (Connection) uses Single Table Inheritance — one connections table with app-specific nullable columns
• DTOs use Map<String, Object> for flexible cross-app credential/result exchange

dto/ — ConnectionRequest / ConnectionResponse

exception/ — GlobalExceptionHandler via @ControllerAdvice

Frontend (frontend/src/)

React 19 + TypeScript + Tailwind CSS, Vite 8 build. Currently basic scaffolding; no significant business logic yet.

Data & AI

• PostgreSQL + pgvector (semantic search via embeddings)
• LiteLLM as a unified AI proxy; Spring AI OpenAI starter wired to it
• Processing pipeline (Phase 2): stage in DB → LLM inference → refine via UI → export to target app

Testing Strategy

Integration tests spin up a mirrored PostgreSQL container on port 5434 (same schema as production). WireMock mocks external HTTP APIs (Homebox, WikiJS). Do not mock the database in integration tests — the mirrored container strategy exists specifically to catch schema/migration divergence.