updated README.MD

README.md

@@ -0,0 +1,86 @@
+## Project Intent
+Vaessl is a **technical playground** and proof-of-concept designed to showcase a complete, professional-grade software lifecycle. The primary goal is not just to build a functional utility, but to demonstrate a multi-experience approach to full-stack engineering, DevOps, and AI integration.
+
+This project serves as a transparent portfolio of my take on:
+* **Infrastructure:** Moving from local-machine to browser-based development environment hosted on my Proxmox server.
+* **Modern AI Orchestration:** Building a system that actually uses AI to do heavy lifting, like identifying objects and understanding natural language using Spring AI and LiteLLM.
+* **Architectural Foresight:** Designing with abstraction layers early to ensure the system can scale from a single-target tool to a multi-app bridge without significant refactoring.
+
+---
+
+## 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.
+
+### 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").
+
+---
+
+## Technical Stack
+
+| Layer | Technology |
+| :--- | :--- |
+| **Backend** | Spring Boot 4.0.x, Java 25 (LTS), Spring AI |
+| **Frontend** | React (Vite), Tailwind CSS, SCSS |
+| **Database** | PostgreSQL + `pgvector` |
+| **AI Gateway** | LiteLLM (Unified API proxy) |
+| **DevOps** | Docker, Portainer, Hoppscotch (API testing), Gitea Actions, Jenkins |
+
+---
+
+## Infrastructure & Methodology
+
+### 1. Centralized Development (Code-Server)
+To maintain a zero-footprint local setup, I develop within a custom **code-server** Docker instance.
+* **Custom Image:** The environment is baked with a specific toolchain (OpenJDK 25, Node.js 24) to ensure absolute environment parity.
+* **Remote Access:** Secured via Pangolin tunnel, allowing for secure, remote development without exposing ports to the public internet.
+
+### 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.
+* **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.
+
+---
+
+## Roadmap
+
+### Phase 1: Foundation
+* [x] Deployment of core infrastructure (PostgreSQL, LiteLLM, Hoppscotch via Docker).
+* [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 3: Semantic Search & Expansion
+* [ ] Integration of Spring AI vector embeddings.
+* [ ] Implementation of additional API targets (WikiJS).
+* [ ] Launch of a 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.
+
+```
+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
+```
+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.