kasun/Vaessl
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects 3 Releases Wiki Activity

revised CLAUDE.md

Browse Source
This commit is contained in:
Kasun Jayatilaka
2026-05-12 20:23:20 +02:00
parent 0eb135249e
commit 4aa3d0134c
1 changed files with 34 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+34 -6
View File
@@ -4,11 +4,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## 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. 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. The frontend has a working connection management dashboard.
## Commands ## Commands
### Backend (Spring Boot + Gradle, inside `backend/`) ### Backend (Spring Boot + Gradle, inside `backend/`)
```bash ```bash
./gradlew build # compile and package ./gradlew build # compile and package
./gradlew test # run all tests ./gradlew test # run all tests
@@ -16,6 +17,7 @@ Vaessl is an AI-powered integration bridge that accepts user text/image inputs,
``` ```
### Frontend (React + Vite, inside `frontend/`) ### Frontend (React + Vite, inside `frontend/`)
```bash ```bash
npm run dev # start dev server npm run dev # start dev server
npm run build # TypeScript check + Vite build npm run build # TypeScript check + Vite build
@@ -27,32 +29,58 @@ npm run test:ui # Vitest visual dashboard
## Environment ## Environment
Copy `.env.local` (not committed) into `backend/` with: Copy `.env.local` (not committed) into `backend/` with:
- `DB_URL`, `DB_TEST_URL`, `DB_USERNAME`, `DB_PASSWORD` — PostgreSQL (test container on port 5434) - `DB_URL`, `DB_TEST_URL`, `DB_USERNAME`, `DB_PASSWORD` — PostgreSQL (test container on port 5434)
- `PG_DRIVER_CLASS_NAME` — PostgreSQL JDBC driver class
- `OPENAI_KEY`, `OPENAI_BASE_URL` — LiteLLM gateway (provider-agnostic, configured for gpt-4o-mini) - `OPENAI_KEY`, `OPENAI_BASE_URL` — LiteLLM gateway (provider-agnostic, configured for gpt-4o-mini)
- `FRONTEND_LOCAL_URL`, `FRONTEND_PUBLIC_URL` — allowed CORS origins for the backend
Frontend (optional, defaults to `/api`):
- `VITE_API_URL` — backend base URL used by `api/client.ts`
## Architecture ## Architecture
### Backend (`backend/src/main/java/com/vaessl/app/`) ### Backend (`backend/src/main/java/com/vaessl/app/`)
Three main modules: Server context path is `/api`. Main endpoints:
- `POST /api/login` — authenticates a service, stores connection ID in session
- `GET /api/connections/status` — lists connected services for the current session
- `DELETE /api/connections/{serviceType}` — removes a service from the session; invalidates the session if no connections remain
Four main modules:
**`config/`**
- `CorsConfig`: env-driven allowed origins (`FRONTEND_LOCAL_URL`, `FRONTEND_PUBLIC_URL`); `allowCredentials(true)` is required for session cookies to work cross-origin
- `SessionConfig`: JDBC-backed Spring Session with a persistent cookie (`SameSite=Lax`, `HttpOnly`)
**`connection/`** — core business logic **`connection/`** — core business logic
- `ConnectionProvider` interface: each integrated app (Homebox, WikiJS) implements `login()` and declares its `ServiceType` - `ConnectionProvider` interface: each integrated app (Homebox, WikiJS) implements `login()` and declares its `ServiceType`
- `ConnectionService`: auto-discovers providers via Spring injection, dispatches login by `ServiceType` - `ConnectionService`: auto-discovers providers via Spring injection, dispatches login by `ServiceType`
- `ConnectionController`: stores `{serviceType}_CONNECTION_ID` in `HttpSession` after login; reads session attributes to build status responses
- Entity (`Connection`) uses **Single Table Inheritance** — one `connections` table with app-specific nullable columns - 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` **`dto/`** — `ConnectionRequest`, `LoginResult`, `AuthResponse`, `ConnectionStatusResponse`
**`exception/`** — `GlobalExceptionHandler` via `@ControllerAdvice` **`exception/`** — `GlobalExceptionHandler` via `@ControllerAdvice`
### Frontend (`frontend/src/`) ### Frontend (`frontend/src/`)
React 19 + TypeScript + Tailwind CSS, Vite 8 build. Currently basic scaffolding; no significant business logic yet. React 19 + TypeScript + SCSS, Vite 8 build.
- `api/client.ts` — typed `apiFetch` wrapper; always sends `credentials: 'include'` for session cookies; base URL from `VITE_API_URL` (defaults to `/api`)
- `api/connections.ts` — connection-specific API calls
- `types/connection.ts` — shared types: `LoginRequest`, `AuthResponse`, `ConnectionStatus`
- `components/Dashboard` — main view listing connected services
- `components/ConnectModal` — login form for adding a service connection
- `components/ServiceCard` — per-service status display
### Data & AI ### Data & AI
- PostgreSQL + pgvector (semantic search via embeddings) - PostgreSQL + pgvector (semantic search via embeddings); also used as the Spring Session store (JDBC)
- LiteLLM as a unified AI proxy; Spring AI OpenAI starter wired to it - 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 - Processing pipeline (Phase 2): stage in DB → LLM inference → refine via UI → export to target app