From 2cbb8b74675750752fdd7a9f36ba23b61dacf998 Mon Sep 17 00:00:00 2001 From: kasun Date: Wed, 22 Apr 2026 18:58:12 +0200 Subject: [PATCH] add CLAUDE.md with architecture and development guidance Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a13bb6a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# 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/`) +```bash +./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/`) +```bash +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` 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.