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

updated readme.md

Browse Source
This commit is contained in:
kasun
2026-06-25 17:56:44 +02:00
parent ff9cfe2b3c
commit 33c560555e
1 changed files with 87 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+87 -24
View File
@@ -9,12 +9,12 @@ This project serves as a transparent portfolio of my take on:
---
## What is Vaessl?
Vaessl acts as translator between user inputs via text or image and digital management systems. It performs image and semantic search analysis before serving results from applications (e.g., Homebox, WikiJS) via REST API.
Vaessl acts as a translator between user inputs via text or image and digital management systems. It performs image and semantic search analysis before serving results from applications (e.g., Homebox, WikiJS) via REST API.
### Core Functionality
* **Staging:** Raw images and metadata are stored in a PostgreSQL staging table.
* **AI-Powered Analysis:** The system utilizes **LiteLLM** as a unified gateway to process inputs via LLM of choice.
* **Semantic Discovery:** By utilizing **Spring AI** and **pgvector**, Vaessl stores description embeddings. This allows for intent-based search (e.g., finding a "Wrench" by searching for "tool to fix a leaky pipe").
* **Connection Management:** Users connect to supported services (e.g. Homebox) via a credential login flow. Tokens are stored in a JDBC-backed HTTP session, enabling secure multi-service connections per browser session.
* **AI-Powered Analysis:** The system utilises **LiteLLM** as a unified gateway to process inputs via LLM of choice *(pipeline in progress)*.
* **Semantic Discovery:** By utilising **Spring AI** and **pgvector**, Vaessl will store description embeddings to enable intent-based search (e.g., finding a "Wrench" by searching for "tool to fix a leaky pipe") *(planned)*.
---
@@ -22,8 +22,8 @@ Vaessl acts as translator between user inputs via text or image and digital mana
| Layer | Technology |
| :--- | :--- |
| **Backend** | Spring Boot 4.0.x, Java 25 (LTS), Spring AI |
| **Frontend** | React (Vite), Tailwind CSS, SCSS |
| **Backend** | Spring Boot 4.1.0, Java 25 (LTS), Spring AI |
| **Frontend** | React 19, Vite 8, SCSS |
| **Database** | PostgreSQL + `pgvector` |
| **AI Gateway** | LiteLLM (Unified API proxy) |
| **DevOps** | Docker, Portainer, Hoppscotch (API testing), Gitea Actions, Jenkins |
@@ -42,12 +42,50 @@ To maintain a zero-footprint local setup, I develop within a custom **code-serve
### 2. Abstraction & Scalability
A core requirement was to prevent vendor or application lock-in:
* **API Abstraction:** While the initial integration targets **Homebox**, the export logic is decoupled. This allows the bridge to support other platforms like **WikiJS** by simply implementing new mapping profiles.
* **Provider Pattern:** Both connection and search logic are fully abstracted behind `ConnectionProvider` and `SearchProvider` interfaces. Adding a new service (e.g. WikiJS) means implementing those interfaces — no changes to core dispatch logic required.
* **AI Agnostic:** LiteLLM abstracts the AI provider, allowing the backend to switch between cloud APIs and local inference engines (Ollama) without code changes.
### 3. Testing Strategy
* **Database Parity:** I utilize mirrored containers for development and testing (`vaessl-db` vs `vassal-test-db`). This ensures that JPA operations are tested against the real PostgreSQL engine and `pgvector` extensions rather than mocks.
* **Frontend TDD:** A Vitest-based stack provides a fast feedback loop for the UI, ensuring component reliability before integration with the Spring Boot backend.
* **Database Parity:** Mirrored PostgreSQL containers are used for development and testing (`vaessl-db` vs `vaessl-test-db`). This ensures JPA operations are tested against the real PostgreSQL engine and `pgvector` extension, not mocks.
* **WireMock:** External HTTP APIs (Homebox, WikiJS) are stubbed in integration tests using WireMock, isolating tests from live service availability.
* **Frontend:** A Vitest-based stack provides a fast feedback loop for UI components.
---
## Architecture Overview
### Backend (`backend/src/main/java/com/vaessl/app/`)
Package-by-feature layout. Server context path is `/api`.
| Package | Purpose |
| :--- | :--- |
| `shared/` | Cross-cutting types: `ServiceType` enum, `ServiceProvider` base interface, `Endpoint` enum, `SessionKeys` utility |
| `config/` | CORS (env-driven allowed origins) and JDBC-backed Spring Session |
| `connection/` | Login, session management, credential persistence (Single Table Inheritance) |
| `search/` | Paged search against connected services, guarded by active session |
| `exception/` | `GlobalExceptionHandler` via `@ControllerAdvice`; domain exceptions mapped to typed HTTP responses |
**REST Endpoints:**
| Method | Path | Description |
| :--- | :--- | :--- |
| `POST` | `/api/login` | Authenticates a service and stores its connection ID in the session |
| `GET` | `/api/connections/status` | Lists all connected services for the current session |
| `DELETE` | `/api/connections/{serviceType}` | Removes a service from the session; invalidates the session if none remain |
| `POST` | `/api/search` | Paged search against a connected service; returns 401 if no active session |
### Frontend (`frontend/src/`)
React 19 + TypeScript + SCSS, Vite 8 build. Package-by-feature under `components/`.
| Module | Description |
| :--- | :--- |
| `api/` | Typed `apiFetch` wrapper + per-feature API call modules (`connections.ts`, `searches.ts`) |
| `types/` | Shared TS types aligned with backend records (`ServiceType`, `LoginRequest`, `SearchResponse`, etc.) |
| `components/connections/` | `Dashboard`, `ConnectModal`, `ServiceCard` — full connection management UI |
| `components/search/` | `SearchModal` — search dialog with paged result rendering |
| `components/ui/` | Shared primitives (`ActionButton`, `Modal`) |
---
@@ -58,32 +96,57 @@ A core requirement was to prevent vendor or application lock-in:
* [x] Custom Code-Server image build and deployment.
* [x] Spring Boot skeleton with Java 25 and Gradle Kotlin DSL.
### Phase 2: The Processing Pipeline (Current)
* [ ] Implementation of Image/Semantic Search $\rightarrow$ AI $\rightarrow$ Staging Table workflow.
* [ ] Development of the data refinement UI in React.
* [ ] Initial API connector for Homebox.
### Phase 2: Connection & Basic Search (Current)
* [x] Provider-pattern abstraction for connections and search.
* [x] Homebox authentication — login, session-tracked token, expiry checking.
* [x] Paged search against Homebox entities via REST.
* [x] React connection management dashboard (connect, disconnect, status).
* [x] React search modal with paged results.
* [x] Integration test suite (WireMock + mirrored PostgreSQL container).
* [ ] Image/text input → LLM inference → staging table workflow.
* [ ] Data refinement UI for reviewing and approving LLM-processed results.
### Phase 3: Semantic Search & Expansion
* [ ] Integration of Spring AI vector embeddings.
* [ ] Implementation of additional API targets (WikiJS).
* [ ] Launch of a public-facing demo.
* [ ] Spring AI vector embeddings with pgvector for intent-based search.
* [ ] Additional API targets (WikiJS).
* [ ] Public-facing demo.
---
## Setup & Deployment
The project is orchestrated via Docker Compose for high portability.
1. Clone the Repository.
2. Environment Setup: Configure `.env.local` with your database credentials and AI API keys.
1. Clone the repository.
2. Copy `.env.local` into `backend/` with:
```
```env
DB_URL=jdbc:postgresql://192.168.1.{subnet}:{port}/vaessl
DB_TEST_URL=jdbc:postgresql://192.168.1.{subnet}:{port}/vaessl_test
DB_USERNAME={username}
DB_PASSWORD={password}
OPENAI_KEY={api-key} # or LLM provider of choice
OPENAI_BASE_URL=https://api.openai.com/v1
PG_DRIVER_CLASS_NAME=org.postgresql.Driver
OPENAI_KEY={api-key}
OPENAI_BASE_URL=https://{litellm-host}/v1
FRONTEND_LOCAL_URL=http://localhost:5173
FRONTEND_PUBLIC_URL=https://{your-public-domain}
```
3. Start the pgvector-enabled PostgreSQL instances (production + test) — use the official `pgvector/pgvector` Docker image or install the extension into your existing PostgreSQL instance.
4. Install frontend dependencies and build the backend:
```bash
# Frontend
cd frontend && npm install
# Backend
cd backend && ./gradlew build
```
5. Run the backend and frontend dev servers:
```bash
# Backend
cd backend && ./gradlew bootRun
# Frontend
cd frontend && npm run dev
```
3. Setup both production and test pgvector databases using the official pgvector docker image or installing the pgvector extension to you existing PostGreSQL database.
4. Execute "npm i" and build gradle.